MkDocs Step by Step: How to Set Up Project Documentation Fast

What Is MkDocs

MkDocs is an easy-to-use static HTML site generator that enables the creation of Project Documentation for end users quickly. It is easy to customize the project documentation as well as the look and feel of the site. The documentation source files use Markdown to format the documentation pages. Configuration of the site uses a YAML configuration file. These combined processes enable the previewing of the site as you work. In addition, it comes with a built-in site search function, allowing the end user to find information faster. Sites built using MkDocs can be hosted anywhere, including GitHub pages and Amazon S3.

What is MkDocs and Why Use It?

MkDocs is a static site generator built specifically for creating project documentation. You write your docs in Markdown, point MkDocs at your files, and it builds a clean, searchable HTML site that you can host anywhere, including GitHub Pages for free.

Compared to alternatives like Sphinx or ReadTheDocs, MkDocs has a very low setup barrier. If you can write a README file, you can use MkDocs. It is particularly useful for data and analytics projects where you want to document methodology, data dictionaries, field definitions, or usage instructions without needing a full web development setup.

When To Use MkDocs

Use it when your project is complex enough that a single README file is no longer sufficient, when you want multiple pages of documentation with navigation, or when you want your project to look professional enough to share publicly or include in a portfolio.

Project Design: Help Files Template Example Site

Screenshot of User Documentation Template

MkDocs Requirements

1. Python (to install the package)

2. Something to edit Markdown files (i.e. Visual Studio Code)

Steps

1. To download the package MkDocs and run the following on the command line

// Installs MkDocs Package

pip install mkdocs

2. Make a new project for MkDocs such as “ProjectDocumentation”. This will generate the mkdocs.yml file, which defines the navigation and site organization. This can be done in the command line prompt.

// To make a new project
// code: mkdocs new [Projecct Name] 

mkdocs new ProjectDocumentation

// Changes Directory
cd ProjectDocumenation

The following files are created:

index.md is the homepage for the documentation
mkdocs.yml is the configuration file and also defines the navigation for the project
The docs folder contains all the markdown pages of the project

3. Running the files will generate a local website. This will allow one to edit the .md / .yml files and the changes in real-time by viewing the local website.

// initiates the local website to enable real-time editing/viewing

mkdocs serve

4. When happy with how things look, build the site using the following code:

// Builds the site

mkdocs build

5. The site can be deployed anywhere. If GitHub is being used, commit the files and run the following:

// Deploys the site using GitHub

mkdocs gh-deploy

There are many different themes that can be used out of the box or customized. There are links to that information and how to create your own theme at MkDocs.org. I also made a GitHub Repo Template and blog post that can be used as a base for your own project. This was inspired by The Document and Usability course, which is a part of The Informatics Technology for Cancer Research (ITCR) Education Resource training series.

References