MkDocs: getting started with a Markdown documentation site

MkDocs is the simplest static-site generator for project documentation that's built around Markdown. Folder of .md files in, fast searchable HTML site out. This guide gets you from zero to a deployed docs site in under 20 minutes, and covers when MkDocs is the right pick vs the alternatives.

What MkDocs is

A Python tool that:

• Reads a directory of .md files
• Renders each to HTML using a Jinja2 template
• Adds navigation, search, and theming
• Outputs a static site you can host anywhere (Netlify, Vercel, GitHub Pages, S3)

That's it. No database, no plugin runtime, no CMS. Edit a .md file, run mkdocs build, deploy.

Install + start a project

pip install mkdocs
mkdocs new my-docs
cd my-docs
mkdocs serve

Open http://127.0.0.1:8000 - you'll see the default MkDocs starter site with one page and a default theme.

The project layout MkDocs created:

my-docs/
  mkdocs.yml          ← site config
  docs/
    index.md          ← homepage

Add more .md files inside docs/ and they become pages automatically.

Theme: install Material for MkDocs

The default theme is functional but plain. Most real-world MkDocs sites use Material for MkDocs, which adds search, dark mode, code-block copy buttons, and a polished design.

pip install mkdocs-material

Then in mkdocs.yml:

theme:
  name: material
  palette:
    primary: blue
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
    - content.code.copy

Re-run mkdocs serve and you'll have a real documentation site.

Writing pages

Each .md file under docs/ becomes a page. Sub-folders become navigation sections. Standard Markdown works:

# Page title

Intro paragraph that becomes the page summary.

## A heading

Body content with **bold**, `code`, [links](other-page.md), images:

![Architecture diagram](images/architecture.png)

Cross-page links use the relative .md path. MkDocs rewrites them to the right HTML route during build.

For the full Markdown syntax reference, see the complete Markdown syntax cheat sheet.

Material for MkDocs extensions worth enabling

markdown_extensions:
  - admonition # callouts: !!! note, !!! warning
  - pymdownx.details # collapsible sections
  - pymdownx.superfences # nested fenced code blocks
  - pymdownx.tabbed # tabbed content (e.g., per-language code samples)
  - pymdownx.highlight # better syntax highlighting
  - tables
  - toc:
      permalink: true # add # anchors to headings

That's the configuration most engineering docs sites converge on.

Build + deploy

mkdocs build              # writes static HTML to site/
mkdocs gh-deploy          # push to gh-pages branch (GitHub Pages)

For Netlify / Vercel:

• Build command: mkdocs build
• Publish directory: site

For Cloudflare Pages / S3: build locally or in CI, upload site/ contents.

MkDocs vs the alternatives

Tool	Language	Strengths	Pick when
MkDocs	Python	Simple, mature, best Material theme	Engineering docs, internal wikis, fast iteration
Docusaurus	React/JS	Versioning, i18n, React components in pages	OSS projects with versioned docs, blogs alongside docs
Astro Starlight	Astro	Performance, ecosystem, MDX	Modern stack, custom components
Hugo	Go	Fastest build times	Sites with thousands of pages
Jekyll	Ruby	GitHub Pages native, mature	Blogs, simple sites, sticking with the GitHub default
VitePress	Vue/JS	Fast dev experience, Vue components	Vue-flavored sites

If you don't have an opinion and you want a fast result for engineering docs: MkDocs + Material is the boring-and-correct choice.

Markdown that breaks MkDocs

MkDocs renders with Python's markdown library (CommonMark + extensions). Things that work elsewhere but break in MkDocs:

• Discord/Slack-specific syntax (||spoiler||, single-asterisk bold) - Markdown lives in many dialects. See Markdown in Discord and Markdown in Slack for those.
• Tables with mismatched column counts - strict Python markdown skips broken tables silently. Repair them first; see How to repair broken Markdown tables.
• Frontmatter beyond YAML - MkDocs supports YAML frontmatter via the meta extension; TOML doesn't work out of the box.

If you're importing existing Markdown from AI assistants or chat, run it through Markdown Tidy first - Tidy normalizes encoding and repairs structural issues that would otherwise break the build.

When to outgrow MkDocs

You'll know it's time to switch when:

• You need page versioning (multiple doc versions side-by-side) - Docusaurus
• You need React/JSX components in pages - Astro Starlight or Docusaurus
• You need internationalization for non-English docs - Docusaurus
• Build times exceed 30 seconds and you have thousands of pages - Hugo

For most internal-team and open-source-project docs, MkDocs handles the job for years.

Related

• What is Markdown? A complete guide - Markdown basics
• Markdown syntax cheat sheet - full reference
• README.md: a writing guide - the entry point to your repo
• GitHub Flavored Markdown - the dialect MkDocs needs to handle