Good documentation deserves better than a wiki nobody updates or a README that scrolls forever. **MkDocs** turns a folder of Markdown files into a fast, searchable static website — no database, no CMS, just Markdown in and a self-contained site out. This guide covers building a docs site with MkDocs and shipping it to your own server with DeployHQ.

## What is MkDocs?

MkDocs is a Python-based static site generator built specifically for project documentation. You write pages in Markdown, describe your navigation in a single YAML file, and MkDocs compiles everything into a static `site/` directory you can host anywhere. Because the output is plain HTML, CSS, and JavaScript, it's fast, secure, and trivial to deploy.

Its most popular companion is the **Material for MkDocs** theme, which adds search, dark mode, navigation tabs, and a polished responsive layout out of the box.

## Installing MkDocs

MkDocs installs via pip. Most projects use it alongside the Material theme:

```bash
pip install mkdocs mkdocs-material
```

Scaffold a new docs project:

```bash
mkdocs new my-docs
cd my-docs
```

You'll get a `docs/` folder with an `index.md` and a `mkdocs.yml` config file.

## Writing and previewing docs

Add Markdown files under `docs/` and wire them into your navigation in `mkdocs.yml`:

```yaml
site_name: My Project Docs
theme:
  name: material

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api.md
```

Run the live-reload dev server to preview as you write:

```bash
mkdocs serve
```

Your docs are now at `http://localhost:8000`, rebuilding on every save.

## Building the static site

When you're ready to publish, build the site:

```bash
mkdocs build
```

MkDocs compiles everything into a `site/` directory — that folder is your entire documentation website, ready to serve as static files. This is the key fact for deployment: **`site/` is the artifact you ship.**

## Deploying MkDocs with DeployHQ

Because MkDocs produces a plain static directory, deploying it is straightforward: build the site in your pipeline, then upload the generated `site/` folder to your server.

Add a [build pipeline](https://www.deployhq.com/features/build-pipelines) that installs MkDocs and builds the site:

```bash
pip install mkdocs mkdocs-material
mkdocs build
```

Then point your deployment at the generated `site/` directory so only the compiled output ships — not your Markdown source or Python dependencies. Enable [automatic deployments](https://www.deployhq.com/features/automatic-deployments) so every push to your docs branch rebuilds and publishes the site, and your documentation is never out of sync with the code it describes.

If you need a specific Python version for the build, set it in your build configuration rather than relying on a local version file — the same way you would when [managing runtimes with mise](https://www.deployhq.com/guides/mise) locally.

## MkDocs vs other documentation generators

MkDocs is the fastest path to a clean docs site if your content is Markdown and your stack is Python-friendly. If you're already in a JavaScript ecosystem, you might prefer a React-based generator — see the [Docusaurus deployment guide](https://www.deployhq.com/guides/deploy-docusaurus) — or an Astro-based one with the [Starlight documentation guide](https://www.deployhq.com/guides/starlight). And if you want documentation components you can embed inside a larger app, the [Markdoc guide](https://www.deployhq.com/guides/markdoc) covers Stripe's framework. All of them share the same deployment shape: build a static site, ship the output.

Ready to publish your docs to your own server? [Create a free DeployHQ account](https://www.deployhq.com/signup) and connect your repository in minutes.