MkDocs

https://www.mkdocs.org/getting-started/

https://www.mkdocs.org/user-guide/writing-your-docs/

Markdown is expected in top-level docs/ dir, with docs/index.md being the home page.

• Install
• Template
• Build
• Preview Locally
• Plugins
  • D2 Embedded Diagrams
• Material
• MkDocs Gotchas
  • Bare URLs Are Not Clickable
  • Quadruple Backticks don't work in MKDocs

Install

pip install mkdocs

Template

HariSekhon/Templates - mkdocs.yml

Build

• build the site/ dir, containing the HTML, Javascript, sitemap.xml and mkdocs/search_index.json
• site/ should be added to .gitignore

mkdocs build

Preview Locally

Launch a local web server at http://127.0.0.1:8000:

mkdocs serve

On Mac, you can open this from the CLI:

open http://127.0.0.1:8000

Plugins

D2 Embedded Diagrams

:octocat: landmaj/mkdocs-d2-plugin

Material

https://squidfunk.github.io/mkdocs-material/

Framework with nice theming built on top of MKDocs.

MkDocs Gotchas

Some things that render fine in Markdown break in MKDocs:

Bare URLs Are Not Clickable

Bare URLs are links on GitHub README.md but not in MKDocs generated pages

Enclose them in < and > to make sure they become links.

Quadruple Backticks don't work in MKDocs

A stray backtick on a triple backticks code block, or an intentional quadruple backticks used to enclose a code sample containing triple backticks (such as seen in the Markdown doc page) will work in GitHub Markdown and IntelliJ local rendering but break formatting in MKDocs.