MkDocs - Project documentation with Markdown

Engineering Nov 22, 2022

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Prerequisites

Knowledge of Markdown syntax
Install latest version of python and python package manager in your system (pip)

Features of Mkdocs

Great themes available
Easy to customize
Preview your site as you work
Host anywhere

Installing MkDocs

(Before moving further for installation and configuration this is assumed that python & Python package manager pre-installed)

Fire the below command in the terminal to install mkdocs in your system:

pip install mkdocs

Check if the mkdocs are successfully installed

Run mkdocs –version, you should see the the result as in below steps

mkdocs, version 1.2.1 from /Users/anuj/.pyenv/versions/3.9.11/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages/mkdocs (Python 3.9)

If all set till this step you have been successfully installed mkdocs in your system

Getting started with Mkdcos

Once the installation process is done, we can start documenting our project with the help of this.

There are much to explore about mkdocs and may cool theme which makes mkdocs documentation more appealing. But for now let’s stick with the main agenda - a glimpse of mkdocs and its working. Please feel free to explore the actual documentation of mkdocs for more insights.

Create new Mkdocs project (documentation project)

Run - mkdocs new PROJECT_DIRECTORY, this command will create a new project with the mentioned project-directory name with it’s default setting

Note - The project directory layout as show below, and comments shown in the below figure states that what file belongs for which purpose.

Start the built in server

Built in server in mkdocs gives us advantage to preview our documentation site, To do the same, we need to run the command - mkdocs serve

Below is a sample of how the we have built the default documentation site till the time.

Recalling the steps what we have done -

Create a new project
Start our built in server to preview

Changing default theme

Open mkdocs.yml this is the main configuration file from where mkdocs could be configured for example - changing themes, adding new plugin, declaring navigation bar etc

On default the mkdocs.yml comes with this default content

site_name: Mkdocs Demo
site_url: https://example.com/

Now let’s change it’s default theme to readthedocs, this theme is more popular in python package documentation, if you have worked on python you might be familiar with readthedocs.org

To change the default theme we just need to add one extra line in our yml configuration file, as shown below

site_name: Mkdocs Demo
site_url: https://example.com/
theme: readthedocs

And Save it, Now go to the browser to see the result, the default theme would look like this

As shown in the bellow reference, this is the way how navigation link to the documentation can be added

Note: all the mentioned MarkDown page ( index.md, about.md) should be in docs/ directory

site_name: Mkdocs Demo
site_url: https://example.com/
theme: readthedocs
nav:
 - Home: index.md
 - Introduction:
     - About Me: about.md
 - FAQ: faq.md

Now following the basic markdown syntax we can design the documentation page, In the example we have to create about.md and faq.md in the docs/ directory and add content in to them.

Reference and links

Above I have provided the glimpse of mkdocs how this works and some of it’s feature still there are many more useful details available to grab and make your documentation looks cool and professional

Some additional links worth taking a look: