Skip to content

Quick Start Guide

Get your MkDocs Material documentation up and running in just 5 minutes!

5-Minute Setup

Step 1: Create Your Project

Create a new directory for your documentation:

mkdir my-docs
cd my-docs

Step 2: Create Configuration

Create a mkdocs.yml file with this minimal configuration:

mkdocs.yml
site_name: My Documentation
site_url: https://example.com
theme:
  name: material
  features:
    - navigation.instant
    - navigation.tabs
    - search.suggest
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Step 3: Create Your First Page

Create the documentation directory and homepage:

mkdir docs

Create docs/index.md:

docs/index.md
# Welcome to My Documentation

This is the homepage of your documentation site.

## Features

- Easy to write with Markdown
- Beautiful Material Design theme
- Fast and responsive

## Getting Started

Start adding your content here!

Step 4: Preview Your Site

Start the development server:

mkdocs serve

Open your browser to http://127.0.0.1:8000

That's it!

You now have a working MkDocs Material site! 🎉

Adding More Pages

Create Additional Pages

Add more pages to your documentation:

Create a new page
echo "# About Page" > docs/about.md
echo "# Features" > docs/features.md

Update Navigation

Add navigation to your mkdocs.yml:

mkdocs.yml
site_name: My Documentation
site_url: https://example.com
theme:
  name: material
  features:
    - navigation.instant
    - navigation.tabs
    - search.suggest
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
    - scheme: slate
      primary: indigo
      accent: indigo
nav:
  - Home: index.md
  - About: about.md
  - Features: features.md

Quick Customizations

Change Colors

Modify the primary and accent colors in your theme:

mkdocs.yml
theme:
  palette:
    - scheme: default
      primary: teal        # Change from indigo
      accent: amber        # Change from indigo

Available colors: red, pink, purple, deep-purple, indigo, blue, light-blue, cyan, teal, green, light-green, lime, yellow, amber, orange, deep-orange, brown, grey, blue-grey, black, white

Add a logo to your site:

  1. Create docs/assets/ directory
  2. Add your logo file (e.g., logo.png)
  3. Update configuration:
mkdocs.yml
theme:
  name: material
  logo: assets/logo.png
  favicon: assets/favicon.png

Enable More Features

Add these popular features to your configuration:

mkdocs.yml
theme:
  features:
    # Navigation
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top

    # Search
    - search.suggest
    - search.highlight
    - search.share

    # Content
    - content.code.copy
    - content.code.annotate

Project Structure

Your project should now look like this:

my-docs/
├── mkdocs.yml          # Configuration file
├── docs/               # Documentation source
│   ├── index.md        # Homepage
│   ├── about.md        # About page
│   ├── features.md     # Features page
│   └── assets/         # Images, etc.
│       └── logo.png    # Your logo
└── site/               # Built site (after mkdocs build)

Next Steps

Essential Additions

  1. Add a requirements file for dependencies:
requirements.txt
mkdocs-material>=9.0
mkdocs-minify-plugin
mkdocs-redirects
  1. Create a .gitignore file:
.gitignore
site/
.cache/
*.pyc
__pycache__/
.DS_Store
  1. Initialize Git (optional):
git init
git add .
git commit -m "Initial documentation setup"

Building for Production

Build your static site:

mkdocs build

This creates a site/ directory with your static HTML files.

Deployment Options

# Install gh-pages deployment tool
pip install mkdocs-material[gh-deploy]

# Deploy to GitHub Pages
mkdocs gh-deploy

Create .gitlab-ci.yml:

image: python:latest
pages:
  stage: deploy
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  only:
    - main
  1. Connect your repository to Netlify
  2. Build command: mkdocs build
  3. Publish directory: site

Checklist

Before moving forward, make sure you've:

  • Created a project directory
  • Added mkdocs.yml configuration
  • Created docs/index.md
  • Tested with mkdocs serve
  • Added additional pages
  • Customized colors or logo
  • Understood the project structure

Common Questions

How do I change the site title?

Update the site_name in your mkdocs.yml:

site_name: Your Site Title
How do I add images?
  1. Place images in docs/assets/images/
  2. Reference in Markdown:
<img loading="lazy" src="assets/images/your-image.png" alt="Alt text">
How do I enable syntax highlighting?

It's enabled by default! Just use code blocks:

```python
def hello():
    print("Hello, World!")
```

Ready for more? Check out the configuration guide to learn about advanced options!