I already wrote about how to build this blog using pelican, how to create sites with Jekyll, and Hyde. In the past I also tried Nikola and even raw HTML. However, since I found out about mkdocs, I gave up all others. Particularly when building quick sites for classes, courses and (obviously) docs.

Mkdocs is extremely simple. All you need is to pip install mkdocs and then

  new        Create a new MkDocs project
  build      Build the MkDocs documentation
  serve      Run the built-in development server
  gh-deploy  Deploy your documentation to GitHub Pages

In that order! Well, you need to flesh a configuration file out after new, and gh-deploy works only if you are hosting your page as a GitHub project page ;-)

Here is a config file example:

site_name: My Awesome Site
pages:
  - Home: index.md
  - About: about.md

theme_dir: custom

site_description: My awesome site
site_url: https://username.github.io/awesome_site
repo_url: https://github.com/username/awesome_site
site_author: Your Name Here
site_favicon: favicon.png
docs_dir: src
site_dir: _site
copyright: Preferably a copyleft ;-)
markdown_extensions:
    - toc:
        permalink: ""
    - extra
    - smarty
    - math
    - markdown_checklist.extension
extra_javascript: ['https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML','js/mathjaxhelper.js']
google_analytics: ['UA-xxxxxx-xx', 'username.github.io']

The file is mostly self explanatory. You need to fill in the information about your site while choosing themes, markdown extensions, etc. Check mkdocs documentation for more information.

The actual pages are in fact just Markdown files. Easy to write, easy to deploy! Once you get the basic config going you can always type mkdocs serve, before editing, your files and the changes will be re-rendered as you type.

Click here to see a rendered example of the results.