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 https://127.0.0.1:8000:

mkdocs serve

On Mac, you can open this from the CLI:

open https://127.0.0.1:8000

Plugins

D2 Embedded Diagrams

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!