Notes on Madrus's Docs

In this documentation, I am collecting tips and tricks that at some point proved to be useful. I am doing it "along the way": every time I get stuck and later later find the solution. Therefore, it is never complete and finished. It is always work in progress.

The website can be seen at http://madrus4u.com/mdocs/.

Basic Installation

• pip install mkdocs
• mkdocs --version
• mkdocs new mdocs
• cd mdocs
• curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md -- Add a new dummy page

Installing prerequisites

In order to view the documents offline, you need Python and the following dependencies:

pip install mkdocs pygments pymdown-extensions
pip install fontawesome-markdown

Running the project in DEV

Open the command prompt in the project root directory and type:

mkdocs serve

Styling

Add some bits and pieces to mkdocs.yml:

site_name: mdocs
pages:
  - Blog: index.md
  - About: about.md
theme: readthedocs

You will notice that the website will look like FeinCMS documentation.

Building the site

• mkdocs build -- build the site
• printf "site/" >> .gitignore
• mkdocs build --clean -- build and clean stale files

Material theme

• pip install mkdocs-material
• add theme: 'material' to the mkdocs.yml
• mkdocs serve

Color names can be written upper- or lowercase but must match the names of the material design color palette. Valid values are: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey and blue grey. The last three colors can only be used as a primary color.

See for more details the Material for MkDocs page. Also a full example configuration for a mkdocs.yml.

Other useful commands

• mkdocs --help
• mkdocs build --help

Deploying to GitHub pages

• git push -u origin master
• mkdocs gh-deploy -- this will build the docs and use ghp-import tool to commit them to the gh-pages branch and push the gh-pages branch to GitHub. Use mkdocs gh-deploy --help to get a full list of options available for the gh-deploy command.

Read the Docs

Read the Docs offers free documentation hosting. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. Read the Docs supports MkDocs out-of-the-box. Follow the instructions on their site to arrange the files in your repository properly, create an account and point it at your publicly hosted repository. If properly configured, your documentation will update each time you push commits to your public repository.

Other themes

• MkDocs Themes
• Bootstrap theme
• 12 Bootswatch themes
• Cinder theme
• Alabaster theme (quite simple)