Skip to main content

MkDocs

Mkdocs. It's a super simple static site generator.

Basics​

mkdocs serve  \\ local copy
mkdocs build  \\ builds site

Github Pages​

The mkdocs build command will generate a site directory with a bunch of .html pages that comprise your static website. However, by default github pages sites will look for the html in a special branch called gh-pages. You could manually create this branch and copy the html files over, but thankfully mkdocs has a command that automates this!

mkdocs gh-deploy

LaTeX​

To get latex working in your project

pip install https://github.com/mitya57/python-markdown-math/archive/master.zip

Then in <your-project>/config.yaml add the following

extra_javascript:
    - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML

markdown_extensions:
    - mdx_math

Material theme​

To get material working in your project

pip install mkdocs-material

Then in <your-project>/config.yaml add the following

theme:
  name: 'material'

PyMdown Extensions​

Official docs. Install with:

$ pip install pymdown-extensions

Then in <your-project>/config.yaml add pymdownx.<extension> to markdown_extensions. For example, to add the Tabbed extension do:

markdown_extensions:
    - pymdownx.tabbed

Examples of how to specify and use each extension here.