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)

naddor / mdocs