MkDocs is the Perfect Open Source Documentation Software

Whether you are a professional software developer looking for a platform to create elegant documentation for one of you projects, or someone working in a company in need to create an internal documentation for staff, or even just a power user who wants to save some notes in a good fashioned way, MkDocs is the best tool for you.

MkDocs is a static site generator which is oriented at creating documentation platforms. It’s quite simple, beautiful and easy to configure and deploy. Written in Python, it simply requires you to create your files in Markdown format, and then, just using a single YAML configuration file, it can generate a working static website out of it for you.

We are happy to share our experience with the software over a period of 12 months of continues usage.

Initial Setup

pip install mkdocs

mkdocs new mkdocsproject

cd mkdocsproject
mkdocs serve

Deployment & Customization

• mkdocsproject/mkdocs.yml: The configuration file for MkDocs.
• mkdocsproject/docs: This is where you place your markdown files in order to be served. Make sure that you have a file called index.md (which will be the front page). You can have pages in sub-directories such as about/something.md.
• mkdocsproject/site: This is where MkDocs will generate the HTML files. Don’t do modifications here.
• mkdocsproject/mkdocs: A small directory for MkDocs assets (such as search functionality).

server {
        server_name example.com;

        root /var/www/mkdocsproject/site;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

sudo service nginx restart

pip install mkdocs-material

site_name: My MkDocs Project
site_url: 'http://example.com'
repo_url: 'https://github.com/username/projecturlongithub'
edit_uri: edit/master
site_description: 'A simple desc here.'
google_analytics: ['UA-xxxxxxxxx-x', 'example.com']
extra:
  favicon: 'https://example/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'mydisqusname'
theme:
  name: 'material'

• repo_url: is your Git repository URL. If you are planning to integrate a Git branch directly into your MkDocs project, then you can use this option to allow people to edit the pages or fork the project directly from your MkDocs project.
• edit_uri: This is the postfix for editing pages, on GitHub, it’s edit/master. It may change if you are using GitLab or GitBucket.
• google_analytics: There’s no control panel for MkDocs. So in order to know who’s visiting your website, you’ll need to use Google Analytics. This option allows you to insert your tracking number in order to associate your account with your website.
• disqus: If you want to enable Disqus comment system on your website, then you can insert your shortname here.
• theme: The name of the theme you want to use.

Example Use Case: FOSS Notes

#!/bin/bash
cd /var/www/fossnotes
rm -rf olddocs
mv docs olddocs
git clone https://github.com/foss-project/fossnotes/ docs
cp posts-cover.svg docs/posts-cover.svg
cd docs
mv README.md index.md
for d in */ ; do
    cd $d
    for file in *.md
      do
        tmpr=${file::-3}
        filename=$(printf "%s" "$tmpr" | tr '[:lower:]' '[:upper:]')
        cp ../posts-cover.svg $filename.oldsvg
        sed "s/DUMMY TEXT/$filename/g" $filename.oldsvg > $filename.svg
        convert $filename.svg $filename.png
        rm $filename.oldsvg $filename.svg
        s="![Tips & notes about $tmpr]($filename.png)"
        sed -i '/^#[^#]/a \'"$s" $file
      done
    cd ..
done

mkdocs build

1. Go to the working directory and remove the olddocs folder. And then move the docs folder (which contains the old copy of the documentation) into the olddocs folder.
2. Clone the GitHub repository into the docs folder.
3. Run a for loop which reads every single Markdown file and takes the title of the document into a string, then using a SVG template we have, make a featured image for the document (by simply replacing the dummy text with the title) and put it in the same folder of the Markdown file, and then insert it into the document.
4. Rebuild the MkDocs project.

Conclusion