Build a Pro Docs Site Fast with MkDocs
#python#documentation#webdev#staticwebapps
Mochammad Farros Fatchur Roji

Mochammad Farros Fatchur Roji @farrosfr

About: Web Developer | Security Enthusiast

Location:
Indonesia
Joined:
Aug 1, 2025

Build a Pro Docs Site Fast with MkDocs

Publish Date: Aug 11
0 0

Image source: snapcraft.io

Introduction

Have you ever found it difficult to manage project documentation? Writing everything in a single Word document is inefficient, as is creating a website from scratch using HTML and CSS. If so, let's get acquainted with MkDocs.

In this article, we will discuss how to create a clean, modern, and functional documentation website in a matter of minutes.

What is MkDocs?

MkDocs is a Static Site Generator (SSG). With it, we can transform Markdown (.md) files and a configuration file into a complete HTML website, ready for hosting.

Why MkDocs?

  • Focus on Content: Concentrate on writing content in Markdown, without worrying about complex HTML.
  • Automatic Navigation: It creates a navigation menu based on your file and folder structure.
  • Fast & Lightweight: The resulting website is static, which makes it very fast.
  • Customizable: Many themes and plugins are available. One of the most popular is Material for MkDocs, which includes features like search, dark mode, and a modern design.

How to Create the Website

Installing MkDocs

Open your terminal and run the following command.

pip install mkdocs mkdocs-material
Enter fullscreen mode Exit fullscreen mode

Creating a New Project

Run this command in your projects folder.

mkdocs new web-documentation
cd web-documentation
Enter fullscreen mode Exit fullscreen mode

This command will create a web-documentation folder with the following structure:

.
├── docs/
│   └── index.md
└── mkdocs.yml
Enter fullscreen mode Exit fullscreen mode
  • docs/: The folder where all your Markdown content files will be stored.
  • mkdocs.yml: The main configuration file for your website.

Project Configuration (mkdocs.yml)

Open the mkdocs.yml file and adjust its content.

For example:

# Basic website information
site_name: My Project Documentation
site_author: FarrosFR

# Use the Material theme
theme:
  name: material

# Navigation Menu Structure
nav:
  - 'Home': 'index.md'
  - 'About': 'about.md'
Enter fullscreen mode Exit fullscreen mode

The configuration above indicates that our website will have two pages in the navigation menu: "Home" and "About".

Adding Content

Now, let's add the content.

Edit docs/index.md (Home):

# Welcome to My Project Documentation

This is the main page for the project documentation. This project aims to...
Enter fullscreen mode Exit fullscreen mode

Create the file docs/about.md (About):

# About the Project

This project was created using MkDocs to simplify documentation management.

## Main Features
- Feature A
- Feature B
- Feature C
Enter fullscreen mode Exit fullscreen mode

Running the Local Server

To see your website live, run the following command.

mkdocs serve
Enter fullscreen mode Exit fullscreen mode

Next, open your browser and navigate to http://127.0.0.1:8000. Whenever you save a change in a .md file, the browser will update automatically.

Building the Website for Production

Once you are satisfied with the result, stop the local server (Ctrl + C) and run the build command.

mkdocs build
Enter fullscreen mode Exit fullscreen mode

This command will create a new folder named site. The contents of this folder are the final version of your website.

Deploying to Hosting

You only need to upload the entire contents of the site folder, as it contains static files.

Alhamdulillah. Thank you for reading, and I hope you find this useful.

Need Web Development Services?

If you need professional assistance in building your website, feel free to contact me.
https://linkedin.com/in/farrosfr/

Comments 0 total

    Add comment