Deploy a Documentation Site with MkDocs and DeployHQ

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:

pip install mkdocs mkdocs-material

Scaffold a new docs project:

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:

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:

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:

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 that installs MkDocs and builds the site:

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 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 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 — or an Astro-based one with the Starlight documentation guide. And if you want documentation components you can embed inside a larger app, the Markdoc guide 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 and connect your repository in minutes.