MkDocs Setup Summary

← Back

---

What is MkDocs?

MkDocs is a static site generator that converts Markdown files into a documentation website. It uses a YAML configuration file (mkdocs.yml) and outputs plain HTML/CSS/JS.

---

Setup Workflow (Mac)

1. Create Virtual Environment

cd your-project
python -m venv mkdocs-env
source mkdocs-env/bin/activate

2. Install MkDocs

pip install mkdocs mkdocs-material

3. Initialize Project

mkdocs new .

This creates: - mkdocs.yml — configuration file (lives in project root) - docs/ — folder for Markdown source files

4. Preview Locally

mkdocs serve

Visit http://127.0.0.1:8000 — includes live reload for most changes.

5. Build Static Site

mkdocs build

Outputs to site/ folder for deployment.

---

Basic Configuration (mkdocs.yml)

site_name: My Documentation
docs_dir: docs
site_dir: site

theme:
  name: material
  palette:
    primary: teal
    accent: orange
  font:
    text: Roboto
    code: Roboto Mono

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Reference: reference.md

---

Available Theme Colors

Primary 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

Accent colors: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange

Schemes: - default — light mode - slate — dark mode

Dark/Light Toggle

theme:
  name: material
  palette:
    - scheme: default
      primary: blue
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: blue
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Custom Hex Colors

theme:
  name: material
  palette:
    primary: custom
    accent: custom

extra_css:
  - stylesheets/extra.css

In docs/stylesheets/extra.css:

:root {
  --md-primary-fg-color: #1e88e5;
  --md-accent-fg-color: #ff6d00;
}

---

Markdown Basics

Headers

# Header 1
## Header 2
### Header 3

Text Formatting

**bold**
*italic*
***bold and italic***
~~strikethrough~~
`inline code`

Links and Images

[link text](https://example.com)
![alt text](images/photo.png)

Lists

- bullet item
- another item
  - nested item

1. numbered item
2. second item

Code Blocks

```python
print("hello world")
```

Tables

| Column 1 | Column 2 |
|----------|----------|
| data     | data     |

Blockquotes

> This is a quote

---

Converting HTML to Markdown

Using Pandoc (recommended)

brew install pandoc
pandoc input.html -o output.md

Online Tools

• codebeautify.org/html-to-markdown
• markdownify.net

After Conversion

mv index.md docs/index.md
mkdocs serve

---

Issues and Resolutions

Issue	Cause	Resolution
config file 'mkdocs.yml' does not exist	Project not initialized	Run mkdocs new . before mkdocs serve
YAML nav changes not showing in browser	Live reload doesn't always catch YAML changes	Manually refresh browser or restart server with Ctrl+C then mkdocs serve
pandoc: command not found after pip install	pip installs Python wrapper, not the binary	Install via Homebrew: brew install pandoc
Virtual environment commands not working	Wrong OS syntax	Mac/Linux: source mkdocs-env/bin/activate / Windows: mkdocs-env\Scripts\activate

---

Key Commands Reference

Command	Purpose
python -m venv mkdocs-env	Create virtual environment
source mkdocs-env/bin/activate	Activate venv (Mac/Linux)
deactivate	Exit virtual environment
pip install mkdocs mkdocs-material	Install MkDocs
mkdocs new .	Initialize project in current directory
mkdocs serve	Run local dev server with live reload
mkdocs build	Generate static site to site/ folder

---

Project Structure

your-project/
├── mkdocs.yml          # config file
├── docs/               # markdown source
│   ├── index.md
│   ├── stylesheets/
│   │   └── extra.css
│   └── images/
└── site/               # generated output (after build)

---

Tips

• Run mkdocs new . in the project root, not in public/ or docs/
• The virtual environment only affects where packages install — files are created in your actual project directory
• mkdocs serve is for development preview; mkdocs build creates files for deployment
• You can embed raw HTML inside Markdown files if needed
• Any Google Font can be used in the font: config

← Back