How to build documentation with MKDocs

Introduction

We live in a Digital Age, an era where there is accelerated technological progress. Many businesses are now using technology to advance their businesses. Developers as well as business owners are constantly building products with the latest technology. How can business owners, developers, and teams provide detailed user guides, project documentation, or API references in a well-organized manner? This is where MKDocs comes in. MKDocs is a static site generator for creating documentation. It can be used to create product user guides, API documentation, operational manuals, and so on.

This article will explain what MKDocs is, the features of MKDocs, how to install it, and a step-by-step guide on how to build documentation with it.

What is MKDocs?

MKDocs is a static site generator that is used for creating documentation from Markdown files. It allows you to build simple, fast, well-organized, and responsive documentation. MKDocs documentation sites are written with Python Markdown and configured with a single file called YAML.

What are the benefits of using MKDocs?

• Customizable and responsive themes

MCKDocs offers varieties of good-looking themes that are responsive. You can choose between built-in themes, select a third-party theme or build your theme.

• Preview your site as you work

MCKDocs allows you to preview your documentation as you work. It auto-reloads and refreshes the browser anytime you save changes made to your work.

• Host Anywhere

You can host your work on GitHub Pages, Amazon S3, or any other place of your choice.

• Simple Configuration

MKDocs uses a simple configuration file called mkdocs.yml to control settings. This configuration file allows you to customize your documentation to your preference and needs. I

• Navigation and Search Features

MKDocs automatically generates a table of contents and navigation sidebar based on your preference, making it easier for users to find information quickly and efficiently.

What are the requirements for installing MKDocs?

To install MKDocs, you need to have the recent version of Python and Python package manager called Pip installed on your computer.

To check if you have Python and pip installed in your system:

• Right-click on your Computer Desktop and click on "Git Bash Here"

  

• Copy and paste the following command into your command line.

 python --version

Your command line will indicate the version of Python in your system as shown in the image below:

• Once, you have confirmed that you have Python installed in your system, check for the pip version too. Copy the command below and paste it into your command line.

pip --version

However, if you do not have Python installed in the system, you will need to install it on your device. Follow the procedure below to install Python and Pip on your device.

• Click on https://www.python.org/. This link will take you to the Python website.

• At the top, hover over Downloads, a drop-down menu will pop up.

• Under Download for Windows, click on the button showing the latest version of Python.

• After downloading, install the Python file on your device. To do this, click on the downloaded file. Before installing, check the box to Add Python.exe to Path.

• Click on Install Now. After installation, a box will pop up showing that the installation was successful.

Installation of Pip

Pip (Python package manager) is most likely in your system if you have the latest version of Python installed in your system. However, you will need to upgrade it using the command below.

pip install --upgrade pip

If you do not have Pip installed in your system, run the following command to install it:

python get-pip.py

How to install MKDocs

MKDocs works with the current version of Python and Pip. If you do not have Python installed in your system, follow the installation guides outlined above. However, if you have the current version of Python on your system, then let us move on to the installation process.

To install MKDocs, run the command below in your command line:

pip install mkdocs

After installation, your command line will indicate that you have successfully installed MKDocs.

Writing your documentation with MKDocs

Documentation is written using a text formatter known as Markdown. It is a lightweight markup language used in MKDocs for creating documentation. To learn more about markdown and how to work with it, click on https://www.markdownguide.org/basic-syntax/. Markdown files are placed inside the documentation directory. This directory is known as "docs" and will be positioned at the top level of your project together with a configuration file known as "yml".

Let's move ahead with creating a project folder.

• On your terminal, run the command below:

mkdocs new my-project

• Move into the folder ("my-project") you created using the command below:

cd my-project

• Move to Visual Studios Code from your terminal by running the command below from your command line:

code .

From the folder, you will see a single configuration file named mkdocs.yml and another folder named docs that contains index.md. "docs" will hold all your documentation source files while "mkdocs.yml" will serve as the central configuration file where you customize various aspect of your site to suite your specific needs and preferences.

Let us view our project on the browser before customizing our documentation to suit our preferences. To do this, go back to your terminal and run the command below:

mkdocs serve

Running the command above, will build your documentation and then, provide your site link. Copy the link and paste it into your browser.

Your project should look like the image below:

MKDocs dev-server supports auto-reloading. This means that it rebuilds as soon as you make changes to your configuration file, theme, or documentation directory.

Having successfully created a project folder and ran it on the browser, let us make changes to the documentation and customize it to our preference using MKDocs as a case study.

Changing the site name and adding the site URL

On your Visual Studio Code(VS Code) or any other code editor of your choice, do the following:

• Click on mkdocs.yml. This will open the configuration file where you will configure your documentation to your preference.

Copy and paste the changes below:

site_name: MKDocs

site_url:  https://example.com/

Adding pages

Let us add the following pages:

• Home Page

• About Page

• User Guide

First, go to your VS Code and create the files above inside the "docs" folder.

Next, we will edit the mkdocs.yml by adding a nav setting to it. Copy the settings below:

nav:
- Home: index.md
- About: about.md
- User Guide: userGuide.md

Your project Home Page should be named index.md by convention.

Next, let us add more information to the About Page and the User Guide page.

Click on the about.md and userguide.md and write your documentation as shown in the images below:

Go to your browser and see the changes you have made.

From the navigation bar, you will see the Home Page, About Page, and User Guide Page on the left as well as the Search, Previous, and Next on the right.

The search button allows users to search for any text on any page.

You can add more pages to your documentation and write to suit your need.

Nesting pages

You can nest pages by listing related pages together. To do this:

• On your VS code, create the files you want to nest.

Note: All files should be created inside the docs folder.

• Next, group related pages under a section title as shown below:

The configuration above contains five top-level items: Home, Getting Started, User Guide, Developer Guide, and About. Home is the link to the homepage, Getting Started" is the link to the getting started page. The "User Guide" has pages nested under it which are: installation.md, writing-your-docs.md, choosing-your-theme.md, customizing-your-theme.md, localizing-your-theme.md and so on. The same format of nesting applies to the "Developer Guide" and the "About".

Your configuration should look like the image below on your browser:

When you click on the drop-down arrow beside any section title, a drop-down menu containing the grouped pages will appear.

Theming your documentation

MKDocs has two built-in themes which are:

1. mkdocs

2. readthedocs

"mkdocs" is the default theme and was built with a custom Bootstrap theme. It supports most features of Macdocs. "readthedocs" theme is a clone of the default theme used by the Read The Docs services. It offers the same restricted feature set as the mkdocs and supports only two levels of navigation. However, there are other third-party themes you can choose from as well.

To choose a theme, go to the mkdoc.yml configuration file and set the theme using the command shown below:

theme: readthedocs

Save the changes and check your browser. You will notice the theme of your documentation has changed.

Conclusion

MkDocs is a static site generator that allows you to create stunning and organized documentation using Markdown files. Its simplicity and flexibility make it an excellent choice for developers, technical writers, content creators, and businesses alike. With Git integration, you can save and manage your documentation in a repository. Additionally, MKDocs offers a wide range of customizable themes, allowing you to tailor your documentation to your preferences and requirement. Whether you need user guides or comprehensive documentation, MkDocs empowers you to build beautiful and well-curated resources for your audience.