using MkDocs

MkDocs converts Markdown to HTML using Python-Markdown.¹

MkDocs uses lunr.js as its search engine², but different themes may have different search plugins.

The serve command starts a web server for local development, generating an HTML preview of changes made to the Markdown-formatted source files.⁷ These changes generally appear in real time.⁸ To access the site, use http://127.0.0.1:8000/¹⁰ or http://localhost:8000/.

Warning

The serve command is only intended for local development⁹ but, because it is not impossible that the site will be accessed by another device on the network, MkDocs should not be used for local management of sensitive information.

Attention

After being built, the site assumes it will come from a server, so when it is opened locally using the file URI scheme there will be problems. Pages will show an "Index of" directory page instead of the actual page, and the search bar will not work. To allow the site to be opened locally, a workaround is to modify the generated site by adding use_directory_urls: false to the MkDocs configuration file and building the site again. This workaround will not change the search bar functionality.

Note

By design, MkDocs does not provide the option of excluding any of the files in docs_dir when building site_dir.^{3 4}

mkdocs.yml configuration file

The MkDocs configuration file is formatted with YAML.

MkDocs supports a number of Python-Markdown¹ and PyMdown extensions, with documentation available from facelessuser and squidfunk. They are enabled and customized through the mkdocs.yml configuration file.

Note

By design, a parent nav item in mkdocs.yml cannot have a page listed after it.⁵

Note

If the repo_url setting is used in the YAML configuration file, automatically-generated edit buttons can be disabled with edit_uri: ''.

Here is part of the mkdocs.yml configuration used for this site:

markdown_extensions:
  - admonition
  - attr_list
  - codehilite:
      guess_lang: false
  - def_list
  - footnotes
  - md_in_html
  - meta
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.keys
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
theme:
  name: 'material'
extra_css:
  - 'extra.css'
extra:
  social:
    - icon: 'fontawesome/brands/github-alt'
      link: 'https://github.com/oronymzy'
repo_name: 'oronymzy/tips'
repo_url: 'https://github.com/oronymzy/tips'
edit_uri: ''

explanation

• The markdown_extensions setting specifies the Python-Markdown extensions for MkDocs.
  • The admonition entry point enables the Python-Markdown admonitions extension.
    Additional documentation is available for Material for MkDocs.
  • The attr_list entry point enables the Python-Markdown attribute lists extension, which adds support for HTML-style attributes using curly brackets ({}) and a CSS-like syntax.
  • The codehilite entry point enables the Python-Markdown Pygments syntax highlighting extension.
    Additional documentation is available for Material for MkDocs, including a list of supported languages. The strings required for each language can be found at the raw text source of the CodeHilite page on GitHub.
    • guess_lang: false disables automatic language detection and ensures that blocks are highlighted only when the language is specified.
  • The def_list entry point enables the Python-Markdown definition lists (or description lists) extension.
  • The footnotes entry point enables the Python-Markdown footnotes extension.
    Additional documentation is available for Material for MkDocs.
  • The md_in_html entry point enables the PyMdown md_in_html extension, which is assumed to function identically to the PyMdown ExtraRawHTML extension. ExtraRawHTML allows parsing of Markdown within any HTML element as long as the markdown="1" attribute is added to its opening tag. It is taken from Python-Markdown Extra, and is also available through the PyMdown Extra and Python-Markdown Extra extension compilations.
  • The meta entry point enables the Python-Markdown metadata (or meta-data) extension, which enables metadata blocks with key-value pairs (or attribute-value pairs) as the contents.
    Additional documentation is available for Material for MkDocs.
  • The pymdownx.caret entry point enables the PyMdown Caret extension, which allows the ins and sup HTML elements to be added using a caret (^).
  • The pymdownx.critic entry point enables the PyMdown Critic extension, which adds support for the CriticMarkup syntax.
  • The pymdownx.details entry point enables the PyMdown Details extension, which adds support for collapsible admonition-style elements using the details and summary HTML elements.
  • The pymdownx.keys entry point enables the PyMdown Keys extension, which allows the kbd HTML element using two plus signs (++).
  • The pymdownx.snippets entry point enables the PyMdown Snippets extension, which allows one Markdown or HTML file into another Markdown file using ASCII scissors (--8<--).
  • The pymdownx.superfences entry point enables the PyMdown SuperFences extension, which expands the functionality of fenced code blocks.
  • The pymdownx.tabbed entry point enables the PyMdown Tabbed extension, which enables tabbed Markdown content.
  • The pymdownx.tasklist entry point enables the PyMdown Tasklist extension, which allows the inclusion of checkboxes to create a (usually non-interactive) task list out of an HTML unordered list.
    • custom_checkbox: true enables CSS styling of checkboxes.
  • The pymdownx.tilde entry point enables the PyMdown Tilde extension, which allows the del and sub HTML elements to be added using a tilde (~).
• The following:

  theme:
    name: 'material'
  

  specifies Material for MkDocs as the MkDocs theme.
• The following:

  extra_css:
    - 'extra.css'
  

  sets an additional CSS file to be included with the theme.
  Additional documentation is available for Material for MkDocs.
• The following:

  extra:
    social:
      - icon: 'fontawesome/brands/github-alt'
        link: 'https://github.com/oronymzy'
  

  is a custom extra setting for the Material for MkDocs theme that adds a social link to GitHub.
• The following:

  repo_name: 'oronymzy/tips'
  repo_url: 'https://github.com/oronymzy/tips'
  edit_uri: ''
  

  adds a GitHub source repository and disables automatically-generated edit buttons.
  Additional documentation is available for Material for MkDocs.

Material for MkDocs theme

Attention

Material for MkDocs expects only one level 1 heading per page. If more than one is included, the table of contents will not display correctly.

Attention

By default, table headers display with a dark gray that can make it difficult to see the dark blue of visited links. A workaround is to introduce an additional stylesheet and add the following to it: .md-typeset table:not([class]) th {background-color: rgba(0, 0, 0, 0.1); color: black;}. This will make the table headers a lighter gray and the text black.

Attention

The Material for MkDocs implementation of lunr.js may behave differently than the default MkDocs implementation of lunr.js.⁶

Attention

Material for MkDocs uses an older version of Font Awesome that does not include some currently-available icons. For example, the social link for Mastodon mastodon does not render, even though there is a Font Awesome icon for it. A workaround is to replace it with something more generic, such as the user icon.

admonition extension

Bug

If a page begins with an admonition, there must be a newline between the first heading and the admonition, or the text between the first and second heading will not be searchable.

Bug

If an admonition contains a table, the table may not render correctly.

Attention

Reference-style links do not work within admonitions.

Attention

Markdown is rendered within HTML when inside admonitions.

licensing

No rights reserved: CC0 1.0.

prior work

• The explanation for MkDoc's difficulty in serving pages opened locally was introduced to me by a comment on GitHub by waylan.
• The explanation for MkDoc's inability to render within HTML block-level elements was introduced to me by a comment on GitHub by facelessuser.
• The explanation for not producing a correct table of contents when a level 1 heading is used was introduced to me by a comment on GitHub by squidfunk.
• The method of disabling automatically-generated edit buttons was introduced to me by a page on the MkDocs website and the Getting started page on the Material for MkDocs website.
• The possibility of using an additional stylesheet to change the appearance of MkDocs was introduced to me by a comment on GitHub by squidfunk.

---

1. https://www.mkdocs.org/user-guide/configuration/#markdown_extensions ↩↩

2. https://www.mkdocs.org/user-guide/configuration/#search ↩

3. https://github.com/mkdocs/mkdocs/issues/1152 ↩

4. https://github.com/mkdocs/mkdocs/issues/1500 ↩

5. https://github.com/mkdocs/mkdocs/issues/1139#issuecomment-281483739 ↩

6. https://github.com/mkdocs/mkdocs/issues/1704#event-2031239880 ↩

7. https://www.mkdocs.org/#preview-your-site-as-you-work ↩

8. http://learn.openwaterfoundation.org/owf-learn-mkdocs/edit/#starting-local-web-server-to-review-content ↩

9. https://github.com/mkdocs/mkdocs/issues/1239#issuecomment-307383410 ↩

10. https://www.mkdocs.org/#getting-started ↩