Skip to content

using MkDocs

MkDocs converts Markdown to HTML using Python-Markdown.1

MkDocs uses lunr.js as its search engine2, 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.7 These changes generally appear in real time.8 To access the site, use or http://localhost:8000/.


The serve command is only intended for local development9 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.


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.


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-Markdown1 and PyMdown extensions, with documentation available from facelessuser and squidfunk. They are enabled and customized through the mkdocs.yml configuration file.


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


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:

  - 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
  name: 'material'
  - 'extra.css'
    - icon: 'fontawesome/brands/github-alt'
      link: ''
repo_name: 'oronymzy/tips'
repo_url: ''
edit_uri: ''


Material for MkDocs theme


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.


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.


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


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


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.


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


Reference-style links do not work within admonitions.


Markdown is rendered within HTML when inside admonitions.


No rights reserved: CC0 1.0.

prior work