DEV Community

Cover image for Document your project with MkDocs and GitHub Pages
Armando C. Santisbon
Armando C. Santisbon

Posted on

Document your project with MkDocs and GitHub Pages

Most project documentation starts with a single file. But for medium and large projects this quickly becomes a really long and hard to manage file. Searching for the content you want, navigation, and styling become a mess.

Enter MkDocs. It can generate a static site that can be hosted on any web server. We'll set it up on GitHub Pages with a configuration that not only makes it look great but allows rich content like math expressions and simplifies deployment.

First install the needed software and create the file structure we'll use.

pip install mkdocs python-markdown-math mkdocs-material
mkdocs new [dir-name]
Enter fullscreen mode Exit fullscreen mode

This will create this default layout

mkdocs.yml    # The configuration file.
docs/  # The documentation homepage.
    ...       # Other markdown pages, images and other files.
Enter fullscreen mode Exit fullscreen mode

GitHub Pages gives you the option to host your static site on any branch in either the root of your project or in a /docs folder so we'll modify the default layout to make our lives easier. Rename /docs to /src/:

mv ./docs/ ./src/
Enter fullscreen mode Exit fullscreen mode

and move the whole dir with mkdocs.yaml and /src/ to your project's directory.

Now edit your mkdocs.yml file to look like this. Replace the placeholders with your GitHub username and repo.

site_name: My Site
site_url: https://<user><repo>/
  - Home: ''
  - toc:
    permalink: "#"
  name: material
    - navigation.expand
    - content.code.copy
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
        icon: material/brightness-5
        name: Switch to dark mode
    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
        icon: material/brightness-3
        name: Switch to light mode
  - mdx_math
  - admonition
  - sane_lists
  - pymdownx.highlight:
      auto_title: false
  - pymdownx.superfences
  - pymdownx.keys
docs_dir: src
edit_uri: edit/main/src/
site_dir: docs
Enter fullscreen mode Exit fullscreen mode

Notice we set docs_dir: src to hold our .md files and site_dir: docs to automatically place the generated site in the folder that GitHub uses to serve our GitHub Pages site.

We're also using the Material theme which is clean, elegant, and has great customization options.

A few extensions we added


  • Pencil: attention, caution, error, hint, important,note.
  • Fire: tip.
  • Exclamation mark: warning.
  • Lightning bolt: danger.

The text must be indented.

!!! attention
    Text goes here.






When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$


Now generate the site. You can use the live-reloading site during development and when you're ready to deploy, build the production site.

  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.

Almost ready!

  • Enable GitHub Pages for your project. Make sure you set it to use the main branch and the /docs folder.
  • Commit your changes and push them to GitHub.

This will kick off a GitHub Action to serve your site. After about a minute it will be available at

Go ahead and create stunning technical documentation for your project!

Top comments (0)