Material for MkDocs Cheat Sheet

---

1. Overview & Installation

What is MkDocs?

• Static site generator for documentation
• Written in Python
• Uses Markdown
• Generates HTML

What is Material for MkDocs?

• Modern theme for MkDocs
• Adds search, tabs, admonitions, icons, Mermaid, dark mode, versioning and more.

Installation

python -m venv .venv
source .venv/bin/activate      # Linux/macOS
# .venv\Scripts\activate       # Windows

pip install mkdocs
pip install mkdocs-material

Create project

mkdocs new .

Run locally

mkdocs serve

Build

mkdocs build

Deploy

mkdocs gh-deploy

---

2. Project Structure

project/
├── docs/
│   ├── index.md
│   ├── guide.md
│   ├── images/
│   └── api/
├── overrides/
├── site/
├── mkdocs.yml
└── requirements.txt

Folder	Purpose
docs	Documentation
images	Images
overrides	HTML overrides
site	Generated website
mkdocs.yml	Configuration

---

3. mkdocs.yml Essentials

site_name: My Docs
site_url: https://example.com

theme:
  name: material

nav:
  - Home: index.md
  - Apache: apache.md

plugins:
  - search

markdown_extensions:
  - admonition
  - footnotes
  - tables
  - pymdownx.details
  - pymdownx.superfences

Recommended settings: - site_name - nav - theme - palette - logo - favicon - repo_url - plugins - extra_css - extra_javascript

---

4. Markdown Essentials

Headings

# H1
## H2
### H3

Table

| Name | Value |
|------|-------|
| A | B |

Image

![Logo](images/logo.png)

Internal Link

[Apache](apache.md)

Code

```python
print("Hello")
```

Footnotes

Reference[^1]

[^1]: Footnote

---

5. Material Components

Admonition

!!! note
    Information

Collapsible

??? tip
    Hidden content

Tabs

=== "Python"

    Content

=== "PHP"

    Content

Task List

- [x] Done
- [ ] Todo

Keyboard

Press ++ctrl+c++

Icon

:material-home:

---

6. Mermaid

Flowchart

```mermaid
flowchart LR
A --> B
B --> C
```

Sequence

```mermaid
sequenceDiagram
A->>B: Hello
```

ER Diagram

```mermaid
erDiagram
USER ||--o{ ORDER : places
```

---

7. Useful Plugins

Plugin	Purpose
search	Search
awesome-pages	Navigation
macros	Variables
redirects	Redirects
blog	Blog
tags	Tags
social	Social cards
glightbox	Image zoom
mike	Versioning

Install

pip install mkdocs-awesome-pages-plugin

Enable

plugins:
  - awesome-pages

---

8. Customization

CSS

extra_css:
  - stylesheets/custom.css

JavaScript

extra_javascript:
  - javascripts/custom.js

Dark Mode

theme:
  palette:
    - scheme: slate

Logo

theme:
  logo: images/logo.png

---

9. Deployment

GitHub Pages

mkdocs gh-deploy

Apache

DocumentRoot /var/www/docs

Nginx

root /var/www/docs;

Docker

FROM squidfunk/mkdocs-material

---

10. Daily Reference

Commands

mkdocs new
mkdocs serve
mkdocs build
mkdocs gh-deploy

Common Extensions

markdown_extensions:
  - admonition
  - attr_list
  - footnotes
  - tables
  - toc
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed
  - pymdownx.highlight
  - pymdownx.keys
  - pymdownx.emoji

Suggested Documentation Layout

docs/
├── index.md
├── linux/
├── apache/
├── mysql/
├── python/
├── php/
├── api/
├── security/
├── architecture/
├── runbooks/
├── troubleshooting/
└── images/

Documentation Checklist

• Purpose
• Installation
• Configuration
• Examples
• Diagrams
• Troubleshooting
• FAQ
• References

AI Prompt

Create documentation in Material for MkDocs format.

Include:
- Overview
- Installation
- Configuration
- Architecture
- Examples
- Mermaid diagrams
- Admonitions
- Troubleshooting
- FAQ
- References

Assume the reader has forgotten everything.