Skip to main content

Mkdocs

Mkdocs is a fast and simple static site generator meant for building project documentation.

Documentation​

Mkdocs Commands​

  • poetry add mkdocs or pipenv install mkdocs - Install mkdocs in environment.
  • mkdocs new [dir-name] - Create a new project.
  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs serve --dev-addr IP:PORT - Run dev docs server in a particular port.
  • mkdocs -h - Print help message and exit.

Building a Static Site​

  • Run mkdocs build on the same directory as the mkdocs.yml file
  • This will create a directory site.
  • To serve static site: python -m http.server <port>

Customization​

  • To install material, poetry add mkdocs-material
  • To change themes, set theme parameter in mkdocs.yml
  • Changing colors for material theme↗️
  • Configure mkdocs to display icons/emojis how-to setup↗️
  • Using icons/emojis in mkdocs how-to use↗️. Refer to this list of icons
    • Use :smile: to display 😄
    • Prefix with material to use material icons :material-account-circle: displays :material-account-circle:
    • Prefix with font-awesome to use font-awesome icons :fontawesome-regular-laugh-wink: displays :fontawesome-regular-laugh-wink:
    • Prefix with octicons to use octicons :octicons-archive-16: displays :octicons-archive-16:
  • Setting up site search site search↗️
  • Local search for static offline site localsearch↗️ -- not yet working
  • Other mkdocs plugins↗️

Project layout​

mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files.

Create a Docker container with mkdocs​

  • Docker pull: docker pull squidfunk/mkdocs-material
  • Run: docker run -d -p <local port>:8000 --name=<container_name> -v <directory_where_mkdocs.yml_is>:/docs squidfunk/mkdocs-material
  • To access, point browser to specified local port.

To create pdf​

  • Make sure weasyprint is installed poetry add weasyprint==52.5. This version of weasyprint would not need new pango features, so no need to install pango either.
  • Install the plugin: poetry add mkdocs-pdf-export-plugin see this↗️
  • For example:
site_name: <name of site>
use_directory_urls: false
theme:
  name: material
markdown_extensions:
    - attr_list
    - md_in_html
plugins:
  - search
  - pdf-export:
          combined: true
          combined_output_path: pdf/<filename.pdf>

The output file will be created in the directory site/pdf/ after doing mkdocs serve and mkdocs build.