# MkDocs Tutorial: Turn Markdown Into a Real Docs Site

## Quick answer

MkDocs turns a folder of Markdown files into a static documentation site: you write pages in Markdown, list them in a small mkdocs.yml file, and run mkdocs build to get plain HTML you can host anywhere. It needs no database and no server code, so the finished site is just files. This post builds a real docs site for the shop orders tool and fixes the one broken nav entry along the way.

The shop orders tool from the earlier Typer post works well from the terminal, but it has a gap: nobody wrote down how to use it. New staff keep asking the same three questions, how to install it, what the commands do, and what to do when list-orders prints nothing. The answers live in chat messages and in one person's head. A short docs site fixes that. MkDocs fits here because the docs are short, mostly text, and the team already writes Markdown. The rest of this post builds that site and shows the build failing once before it works.

## What I would check before using it

My first check is what the docs contain. MkDocs is built for pages of text, headings, lists, and code samples. If the docs need a live API playground, user accounts, or per-visitor pages, a static site is the wrong shape. The [FastAPI Explained: Python APIs at Full Speed](https://practicaldevblog.blogspot.com/2026/10/fastapi-explained-python-apis-at-full.html) post shows what that dynamic side looks like.

My second check is the size of the site. A hand-written nav list is easy to keep right for four pages, or forty. Past a few hundred pages it turns into a chore, and a folder-built nav saves real time.

My third check is hosting. The build output is plain HTML, CSS, and JavaScript, so any static host works: GitHub Pages, Netlify, Cloudflare Pages, or a plain web server. No server process runs, no database needs backing up, the same reason the [Hugo Explained: Blazing-Fast Static Sites From Go](https://practicaldevblog.blogspot.com/2026/10/hugo-explained-blazing-fast-static.html) post gives for static sites.

My fourth check is the writing format. MkDocs pages are Markdown files, so the team needs to be comfortable writing Markdown and editing a small YAML file. The [Markdown Explained: Writing That Becomes Any Format](https://practicaldevblog.blogspot.com/2026/10/markdown-explained-writing-that-becomes.html) post covers the format, and the [uv Python Tutorial: Manage Projects Without the Mess](https://practicaldevblog.blogspot.com/2026/11/uv-python-package-manager.html) post shows a tidy Python setup.

My fifth check is the theme: the built-in theme is plain but readable, and its search works without a server.

My verdict, as judgement: use MkDocs for small to medium Markdown docs for people happy in a text editor. The recommendation flips if the docs need logins or dynamic content, if non-technical editors need a visual editor, or if the page count outgrows a hand-kept nav list.

## Four pages, one config file, and a broken nav entry

The docs site covers the orders tool from the [Typer post](https://practicaldevblog.blogspot.com/2026/11/typer-python-cli-tutorial.html), in four pages: index, installation, commands, and troubleshooting. First, install MkDocs. Plain pip was refused here because this system Python is externally managed, so the install used the --user flag.

```
$ pip install --user --break-system-packages mkdocs
Successfully installed click-8.5.1 ghp-import-2.1.0 jinja2-3.1.6 markupsafe-3.0.4 mergedeep-1.3.4 mkdocs-1.6.1 mkdocs-get-deps-0.2.2 pathspec-1.1.1 pyyaml-env-tag-1.1 watchdog-7.1.1
```

```
$ python3 -m mkdocs --version
python -m mkdocs, version 1.6.1 from /home/hatch/.local/lib/python3.12/site-packages/mkdocs (Python 3.12)
```

The project is a mkdocs.yml file at the root and a docs folder with one Markdown file per page. The nav list sets the page order and the labels readers see.

```yaml
site_name: Orders Docs
site_description: Help for the shop orders tool
theme:
  name: mkdocs
nav:
  - Home: index.md
  - Installation: installation.md
  - Commands: commands.md
  - Troubleshooting: troubleshooting.md
```

```markdown
# Orders Docs

The orders tool records shop orders, lists them, and totals sales per city.

Start with the [installation guide](installation.md), then read the [commands](commands.md). If something breaks, check [troubleshooting](troubleshooting.md).
```

The installation page states the Python version, one command to check the tool runs, and the data file location.

```markdown
# Installation

You need Python 3.10 or newer. Copy `orders.py` into a folder, then check it runs.

    python3 orders.py --help

The tool stores orders in `orders.json` next to the script.
```

The commands page shows the three commands with a real example and one line on what each does.

```markdown
# Commands

Three commands cover the daily routine.

    orders add --customer Ayesha --city Karachi --total 12400
    orders list-orders
    orders totals

`add` records one order. `list-orders` shows every order on file. `totals` prints sales per city and a grand total.
```

The troubleshooting page covers the failure new users hit most: running the tool from the wrong folder.

```markdown
# Troubleshooting

If `list-orders` prints "No orders yet", check you are in the folder holding `orders.json`. If `add` rejects a total, it must be a positive number.
```

The first build failed: the config had one extra nav line, a Shipping page pointing at shipping.md, but no such file existed in the docs folder. With --strict, the warning became a failed build.

```
$ python3 -m mkdocs build --strict
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/hatch/workspace/.toolchains/verify/batch56-mkdocs/site
WARNING -  A reference to 'shipping.md' is included in the 'nav' configuration, which is not found in the documentation files.

Aborted with 1 warnings in strict mode!
```

The fix: delete the Shipping line from the nav list, since the shop has no shipping page yet. The next build finished in 0.08 seconds with four HTML pages, one per Markdown file, plus the search index and sitemap.

```
$ python3 -m mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/hatch/workspace/.toolchains/verify/batch56-mkdocs/site
INFO    -  Documentation built in 0.08 seconds
```

The last check served the built site and fetched pages with curl. The home, commands, and troubleshooting pages each returned HTTP 200, the home page title was "Orders Docs", and the commands page held the real add command.

```
$ python3 -m http.server 8123 --directory site
$ curl -s -o /dev/null -w "index: %{http_code}\n" http://127.0.0.1:8123/
index: 200
$ curl -s -o /dev/null -w "commands: %{http_code}\n" http://127.0.0.1:8123/commands/
commands: 200
$ curl -s http://127.0.0.1:8123/ | grep -o '<title>[^<]*</title>'
<title>Orders Docs</title>
$ curl -s http://127.0.0.1:8123/commands/ | grep -o 'orders add[^<]*'
orders add --customer Ayesha --city Karachi --total 12400
```

## Common mistakes and how to fix them

First, a nav entry for a file that does not exist. The symptom is the warning "A reference to 'shipping.md' is included in the 'nav' configuration, which is not found in the documentation files." and, with --strict, "Aborted with 1 warnings in strict mode!" and exit code 1. The fix is to create the missing file or delete the nav line.

Second, a tab character in mkdocs.yml. The symptom is "found character '\t' that cannot start any token" with exit code 1, because YAML forbids tabs for indentation. The fix is to indent with spaces only.

Third, running mkdocs build from the wrong folder. The symptom is "Error: Config file 'mkdocs.yml' does not exist." with exit code 1. The fix is to cd into the project folder first.

Fourth, editing the built files under site/ instead of the sources under docs/. The symptom is that the changes vanish on the next build, because the build cleans that folder first. The fix is to edit only the Markdown under docs/ and rebuild.

## Frequently Asked Questions

Is MkDocs the same as Hugo? No. Hugo is a static site generator for blogs and docs, while MkDocs is built for documentation only. Hugo fits a whole website; MkDocs fits a docs folder.

Do readers need Python to read the site? No. Python and MkDocs are needed only to build the site. Readers open plain HTML in a browser, so the finished site works on any static host.

Can I change how the site looks? Yes. MkDocs ships with a built-in theme, and third-party themes such as Material for MkDocs add stronger navigation, search, and branding. A theme is one line in mkdocs.yml.

Where can I host the built site? Anywhere static files are served: GitHub Pages, Netlify, Cloudflare Pages, or a plain web server. Copy the built site folder; there is no server process or database to keep running.

## What to remember

- MkDocs turns Markdown files and a small mkdocs.yml into a static docs site.
- The nav list sets page order and labels, and every entry needs a real file.
- Run mkdocs build from the project folder, and check the output before sharing.
- The site folder is generated: edit the Markdown under docs/, never the HTML under site/.
- The built site is plain files, so any static host can serve it.

## Where this leaves you

MkDocs earns its place the moment project docs outgrow a single README and the same questions start repeating. The demo proved it: four short pages and one config file became a searchable site in 0.08 seconds, and the broken nav entry failed loudly instead of publishing a dead link. Take a tool you already built, write down the three questions new users always ask, and put the answers in a docs folder. A docs site that builds in under a second stays easy to keep current, and current docs beat clever docs every time.

## Further reading

- [MkDocs documentation](https://www.mkdocs.org/)
- [Material for MkDocs documentation](https://squidfunk.github.io/mkdocs-material/)
- [MkDocs on GitHub](https://github.com/mkdocs/mkdocs)
- [Markdown Explained: Writing That Becomes Any Format](https://practicaldevblog.blogspot.com/2026/10/markdown-explained-writing-that-becomes.html)
- [Hugo Explained: Blazing-Fast Static Sites From Go](https://practicaldevblog.blogspot.com/2026/10/hugo-explained-blazing-fast-static.html)
- [Typer Python CLI Tutorial: Build a Real Orders Tool](https://practicaldevblog.blogspot.com/2026/11/typer-python-cli-tutorial.html)
- [uv Python Tutorial: Manage Projects Without the Mess](https://practicaldevblog.blogspot.com/2026/11/uv-python-package-manager.html)

Waqas Shahid is a software engineer from Karachi with more than 12 years of experience, including 6+ years in engineering leadership. He writes The Practical Developer.

