Mkdocs Material¶

Official doc¶

Plugins¶

mkdocs/catalog is a list of awesome MkDocs projects and plugins.

Selected¶

mkdocs-awesome-pages-plugin sorts pages in navigation section (descending order)
mkdocs-git-revision-date-localized-plugin adds the date on which a Markdown file was last updated at the bottom of each page
mkdocs-rss-plugin generates a RSS feeds for created and updated pages, using git log and YAML frontmatter (page.meta)
mkdocs-section-index allows clickable sections that lead to an index page.
mkdocs-literate-nav specifies the navigation in Markdown instead of YAML
mkdocs-gen-files programmatically generate documentation pages during the build
mkdocs-same-dir allows placing `mkdocs.yml`` in the same directory as documentation
mkdocstrings automatic documentation from sources

Deployment¶

github-action-push-to-another-repository
mkdocs-material Github Action - clean sample for site deployment

Tips and Tricks¶

Code blocks¶

I have discovered that enabling code block title and line numbers globally (in mkdocs.yml) is bad idea:

mkdocs.yml

markdown_extensions:
- pymdownx.highlight: # (1)!
    auto_title: true
    linenums: true

Code annotations PyMdown Extensions - Highlight options

that’s why I will switch on title and line numbers on demand (see more here):

Code block with title

``` py title="bubble_sort.py"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

bubble_sort.py

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Code block with line numbers

``` py linenums="1"
def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]
```

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Render Markdown in `<details />` tag¶

Use md_in_html to render collapsible blocks, which are implemented with <details /> elements (see issue Formatting lost in <details> tag):

markdown_extensions:
  - md_in_html

<details markdown>
  <summary>Title</summary>
  Content
</details>