Build a Manual with MkDocs #1: From Install to Your First Doc

Framework MkDocs Documentation Static Site
4 min read

When you start building documentation in earnest, you almost always run into the same problem: where do you put documentation that a single README can no longer handle? Notion is awkward for public access and version control, and blog tools just line posts up chronologically, which makes them inconvenient as a reference. So many teams shift to treating docs like code, that is, Docs as Code. You write in Markdown, manage it with Git, and deploy it as a static site.

This series covers that first step: building a documentation site with a static site generator. The tool is MkDocs. It’s written in Python and has simple configuration, so it’s the lowest-barrier choice especially for teams already using Python. For the theme, we’ll use Material for MkDocs, which is built specifically for documentation.

This series, Build a Manual with MkDocs, runs in six parts.

  • #1: From Install to Your First Doc ← this post
  • #2: nav and Search — Shaping the Information Structure of Your Docs
  • #3: Writing Content — Code Blocks, Mermaid, and Admonitions
  • #4: Deploy on Cloudflare Pages and Connect a Domain
  • #5: Multilingual Docs and Versioning
  • #6: Maintenance — Search, Accessibility, and Documentation Culture

In this post we’ll see firsthand what MkDocs requires as prerequisites, and how to create a new site, apply the Material theme, and serve your first doc locally.

Prerequisites — Python Is All You Need #

MkDocs is a Python package, so its prerequisites are simple too. All you need is Python 3 and pip. Unlike Hugo, which ships as a single binary but also requires Go, you can start right away if you already have a Python environment set up.

Installation #

We recommend installing inside a per-project virtual environment (venv). This keeps your system Python clean and lets you manage the documentation tool version separately for each project.

Installation (virtual environment recommended) 
# Create and activate a virtual environment in the project folder
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

# Install the Material theme (mkdocs itself is pulled in too)
pip install mkdocs-material

Installing mkdocs-material brings in MkDocs itself as a dependency. After installing, check the version.

Check the version 
mkdocs --version

Creating a New Site #

Create the skeleton of an empty documentation site. To generate it directly in the current folder, pass a dot (.) as the argument.

Create a new site 
mkdocs new .

This command creates two things: the configuration file mkdocs.yml, and docs/index.md, which holds your first doc. All docs accumulate inside the docs folder.

Applying the Material Theme #

Open the generated mkdocs.yml and set the theme to Material. The default is a plain built-in theme, so changing just this one line turns it into a documentation site with search, dark mode, and responsive layout built in.

mkdocs.yml 
site_name: Product Manual
theme:
  name: material

Serving Your First Doc #

Now start the local server. When you edit a file, the screen refreshes automatically.

Run the local server 
mkdocs serve

Open http://127.0.0.1:8000 in your browser and your first doc appears in the Material layout. Let’s add one more doc. Just create a file in the docs folder.

Add a doc 
# Create docs/getting-started.md and fill in the body

Understanding the Folder Structure #

In the structure you’ve built so far, the only things you need to know right now are the single docs folder and the configuration file.

Folder structure 
my-docs/
├─ mkdocs.yml         # Site configuration
├─ docs/              # Doc bodies (just fill this in)
│  ├─ index.md        # First screen
│  └─ getting-started.md
└─ site/              # mkdocs build output (for deployment)

Growing your docs ultimately comes down to adding more Markdown files under docs. That said, unlike Hugo, which uses the folder structure directly as the sidebar, MkDocs lets you write the sidebar (nav) directly in mkdocs.yml to control the order and grouping. We’ll cover that in earnest in the next post.

Wrapping Up #

In this post we installed MkDocs Material into a Python virtual environment, applied the theme to a new site, and served our first doc locally. The biggest advantage of MkDocs is that a single line of configuration gets you a documentation site that already has search.

In the next post we’ll cover nav and search. It’s the stage where you design the information structure with mkdocs.yml so readers don’t get lost even when the docs grow to dozens of pages.

X