Skip to content

Creating Project Documentation

Using MkDocs

  • Uses markdown.
  • Works with github pages.
  • Every project will have their own documentation
    • Styleguide should be included (frontend)
    • Project goals and requirements
    • Notes about development
    • Setup/install instructions
    • Resolution to issues (ongoing FAQ for the projects)
  • Documentation pages stay in gh-pages branch.


  • Use pipenv
  • Create project directory and CD into it
  • Install mkdocs as dev dependency - pipenv install mkdocs --dev
  • Create mkdocs direcotry - mkdocs new sitedocs
  • sitedocs\docs is where the markdown goes.
  • sitedocs\mkdocs.yml - your table of contents.


  • mkdocs serve - local development server http:\localhost:8000
  • mkdocs gh-deploy - build docs and push to gh-pages repo in github after committing.

Config file - mkdocs.yml

site_name: Development Notes for Johan Martin
site_description: Notes tracking for developing different apps.
site_author: Johan Martin (
repo_name: 'GitHub'
edit_uri: edit/master/md/
# docs_dir: 'md'
# site_dir: 'docs'
copyright: Johan Martin © 2017
  - pymdownx.tilde
theme: 'material'
- Home: ''
- Section:
  - 'Page Sites': ''
  - Section: 
      - sub1: ''
      - sub2: ''

MkDocs Notes

Installing Markdown Extensions

Fixing Issues with MkDocs

404 error for home page/front page - github gh-pages hosting. : Seems like the home page has to point to an "" page for it to work. * RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment. Consult mitigation steps. * Fix with: * > export LC_ALL=en_US.UTF-8 * > export LANG=en_US.UTF-8

Importing docs into Github

  • ghp-import
  • Already being used by MkDocs.
  • Would like to use with Sphinx if I convert my documentation to Sphinx.