MkDocs

lastmod 2026-04-01created 2023-07-1330 edits

MKDocs is a writing tool. There are many writing tools, such as sphinx and read docs. I chose MKDocs because it is simple, you write in markdown, and the serve command lets you see what you're writing in real time.

Categories

Plugins

• Material for MkDocs
• mkdocs-minify-plugin - A mkdocs plugin to minify the HTML of a page before it is written to disk.
• mkdocs-alias-plugin - An MkDocs plugin allowing links to your pages using a custom alias
• mkdocs-autolinks-plugin - An MkDocs plugin that automagically generates relative links between markdown pages
• mkdocs-meta-descriptions-plugin - 📑 Generate meta descriptions from the first paragraphs in your MkDocs pages
• mkdocs-minify-plugin - A mkdocs plugin to minify the HTML of a page before it is written to disk.
• mkdocs-ezlinks-plugin - Plugin for mkdocs which enables easier linking between pages
• mkdocs-redirects - Open source plugin for Mkdocs page redirects
• mkdocs-print-site-plugin - Combines all pages into a single page, making it easy to export to PDF and standalone HTML.
• mkdocs-simple-hooks - Lets you hook in without creating a new package.
• mkdocs-exclude - Sets conditions for excluding files from documentation.
• mkdocs-literate-nav - Lets you configure nav in a separate page instead of mkdocs.yml.
• mkdocs-extract-listings-plugin - Lists all pages.
• mkdocs-pagetree-plugin - Outputs a page tree.

Markdown Extensions

Add the following to the mkdocs.yml file:

markdown_extensions:
  - md_in_html
  - pymdownx.arithmatex:
      generic: true

See Python-Markdown#Extensions for the full list.

How to generate sitemap.xml

sitemap.xml is generated only if you set site_url in the mkdocs.yml file:

site_name: "My Docs"
site_url: "https://example.com/docs/"

Linking to pages

• Writing Your Docs - MkDocs

Troubleshooting

Doc file 'XXX.md' contains a link 'YYY.md', but the target is not found among documentation files

Doc file 'Index.md' contains a link 'mutex.md', but the target is not found among documentation files.

A warning raised when a file is linked but cannot be found.

Doc file 'xxx.md' contains an absolute link '/yyy.md', it was left as is.

INFO    -  Doc file '1BITDRAGON.md' contains an absolute link '/Music.md', it was left as is.
INFO    -  Doc file '1BITDRAGON.md' contains an absolute link '/Scorewriter.md', it was left as is.

To hide the log, in the mkdocs.yml file:

validation:
  links:
    absolute_links: ignore

See also

• Documentation generator
• YAML frontmatter
• SSG
• Docusaurus
• Zensical
• PageFind

Favorite site

• MkDocs web site
• Getting Started - MkDocs
• Home - MKDocs Tutorial
• 6.6 MkDocs - Python for Engineers
• [Recommended] mkdocs/catalog: 🏆 📚 A list of awesome MkDocs projects and plugins.
• Blimped | Creating a beautiful documentation site with MkDocs