Create Static HTML Site Using MkDocs

In this tutorial, we will show you how to create static HTML based documentation using MkDocs

Build documentation using MkDocs

MkDocs is an HTML site generator that helps in building project documentation. In this section, we will generate a static website using MkDocs material theme.

Install MkDocs

Create a python virtual environment. We will install MkDocs in this virtual environment.

python3 -m venv mkdocs_venv
source mkdocs_venv/bin/activate
pip3 install mkdocs

Install Material Theme for MkDocs

MkDocs includes built-in themes as well as supports third party themes for its static webistes. We will use Material theme for our static website. Install mkdocs-material package using pip3 inside virtual environment we just created

pip3 install mkdocs-material

Create Static Site

Execute following command to create initial site

mkdocs new pulleycloud
cd pulleycloud

This creates a boilerplate MkDocs based documentation. You can see the documentation by executing mkdocs serve

$ mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.06 seconds
INFO     -  [22:53:27] Serving on http://127.0.0.1:8000/

Hit the end-point on your browser. You should see mkdocs themed webiste as follows:

We will update mkdocs.yaml to use material theme. Put following content in your mkdocs.yaml configuration file.

site_name: Documentation website for PulleyCloud
site_url: https://www.put-your-domain-here.com
theme: 
  name: material
  icon:
    repo: fontawesome/brands/github
  features:
    - navigation.tabs
nav:
    - Home: "index.md"
    - Topics: 
      - Topic-1: "topic-1/index.md"
      - Topic-2: "topic-2/index.md"

The nav parameter above creates navigation with Home and Topics menu. The Topics menu has sub-menu items as well.

We will now add content to the page for our menu items. The content is expressed using Markdown syntax

Home Page Markdown Content

Our Home page uses docs/index.md markdown file to render its HTML content. Modify it as follows:

# Welcome to Documentation website for PulleyCloud
This site hosts documentation for PulleyCloud

Topics Page Markdown Content

Topics menu item has 2 sub-menu items. Create directory to hold markdown contents for Topic-1 and Topic-2.

$ mkdir docs/topic-1  docs/topic-2
$ ls docs
index.md    topic-1/        topic-2/

Add following markdown content for Topic-1 and Topic-1

Topic-1

Populate docs/topic-1/index.md file with:

# This is topic 1 documentation
## sub-topic 1
This is sub-topic 1
## sub-topic 2
This is sub-topic 2

Topic-2

Populate docs/topic-2/index.md file with:

# This is topic 2 documentation
## sub-topic 1
This is sub-topic 1
## sub-topic 2
This is sub-topic 2

Verify Documentation Website

Execute mkdocs serve and hit the endpoint to browse our Documentation website. You should see documentation as follows

Home Page

Topics Page

That't it! Now that we have seen how to generate HTML based documentation using MkDocs, it's time to take this content and host it using NGINX based web server.

Have any feedback?

If you have any feedback regarding this article or need tutorial on any specific topic, please submit this feedback form.