MkDocs Markdown Quick Reference Card

Commands

Command	Purpose
`mkdocs serve`	Live preview at localhost:8000
`mkdocs build`	Generate static site
`mkdocs new [name]`	Create new project
`mkdocs build --clean`	Clean build

Text Formatting

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

Headers

# H1 - Page Title (one per page)
## H2 - Major Section
### H3 - Subsection
#### H4 - Sub-subsection

Lists

Unordered:

- Item
- Item
  - Nested (2 spaces)

Ordered:

1. Step one
2. Step two
   1. Sub-step (3 spaces)

Lazy numbering: Use 1. for all items—Markdown auto-numbers.

Links & Images

[Link text](https://example.com)
[Internal link](../week02/index.md)
[Section link](#header-name)
[Download](files/myfile.pdf)

![Alt text](files/image.jpg)
![Sized image](files/image.jpg){ width="300" }

Memory trick: Links use [text](url) — Images add ! in front.

Tables

| Left   | Center  | Right  |
|:-------|:-------:|-------:|
| L      |    C    |      R |

Colons point toward alignment direction.

Code Blocks

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

```bash
mkdocs serve
```

Languages: python, bash, html, css, javascript, c, yaml, json

Blockquotes

> Quote text
> Continues here

Horizontal Rule

---

Material Theme Admonitions

!!! note "Title"
    Content indented 4 spaces.

!!! warning
    Warning message.

!!! tip
    Helpful hint.

Types: note, tip, warning, danger, info, success, question, example

Collapsible:

??? note "Click to expand"
    Hidden content.

???+ note "Starts open"
    Visible content.

Task Lists

- [x] Done
- [ ] Todo

Memory Tricks

Element	Remember
`bold`	Double stars = double strong
`italic`	Single star = subtle
`[text](url)`	Brackets hold words, parens hold path
`![](img)`	Excited `!` = visual content
`#` headers	More `#` = smaller (like weight class)
`-` vs `1.`	Dash = bullets, numbers = steps
`\\|` tables	Pipes are cell walls
`:` alignment	Colons point the direction

Fab Academy Paths

[Download file](files/filename.ext)
![Image](files/photo.jpg){ width="400" }
[Another week](../weekXX/index.md)

MkDocs Configuration & Features

Useful Theme Features

Add these to your mkdocs.yml under the theme section:

theme:
  name: material
  features:
    - navigation.indexes
    - navigation.tabs
    - navigation.tabs.sticky
    - content.code.copy      # Adds copy button to code blocks
    - content.code.annotate  # Allows annotations in code

Enhanced Code Blocks

For syntax highlighting and better code block support, add these extensions:

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences

If you get an error about pymdownx.superfences, install the extension:

pip install pymdown-extensions

Abbreviations (Hover Definitions)

Add tooltip definitions for terms. First enable the extension:

markdown_extensions:
  - abbr

Then in your markdown:

The CNC uses a spindle to cut material.

*[CNC]: Computer Numerical Control
*[spindle]: Rotating component that holds the cutting bit

Hover over "CNC" or "spindle" to see the definition.

Link Tooltips

Add a title attribute for simple hover text on links:

[Dremel CNC](final-project.md "My final project: a small CNC using a Dremel as the spindle")

Virtual Environment Quick Reference

Action	Command
Create venv	`python3 -m venv venv`
Activate venv	`source venv/bin/activate`
Deactivate venv	`deactivate`
Check if active	Look for `(venv)` in your prompt
Install MkDocs	`pip install mkdocs mkdocs-material`
Install extensions	`pip install pymdown-extensions`
Preview site	`mkdocs serve`

Common Issues & Fixes

Issue	Cause	Fix
`mkdocs: command not found`	Virtual environment not activated	Run `source venv/bin/activate`
`Failed to load extension 'pymdownx.superfences'`	Extension not installed	Run `pip install pymdown-extensions`
Copy button not appearing	Wrong feature name	Use `content.code.copy` (not `content.copy.code`)
Admonitions not rendering	Extension not enabled	Add `- admonition` to `markdown_extensions`

Added 2/4/2026

Automatic Heading Anchors

MkDocs automatically generates anchor IDs for all headings by converting them to lowercase and replacing spaces with hyphens.

Heading	Auto-Generated Anchor
`## My Section`	`#my-section`
`## Week 2: CAD Design`	`#week-2-cad-design`
`## 3D Printing Setup`	`#3d-printing-setup`

[Jump to My Section](#my-section)

Custom Anchor IDs

Use the {#custom-id} syntax to define your own anchor ID for a heading. Requires the attr_list extension.

## My Section {#custom-id}

[Link to custom anchor](#custom-id)

Inline Anchors (Without Headings)

To create an anchor point anywhere in your document without a visible heading:

Method 1: Using attr_list

Some important text here. {#my-anchor}

[Jump to that text](#my-anchor)

Method 2: Using HTML

<a id="my-anchor"></a>

[Jump to anchor](#my-anchor)

Cross-Page Links

Link to a specific section on another page by combining the relative file path with the anchor.

[Link to section on another page](other-page.md#section-name)

[Week 1 Documentation](fab_w01_overview.md#materials-list)

Required Configuration

Add attr_list to your mkdocs.yml to enable custom anchor IDs:

markdown_extensions:
  - attr_list

Print this and keep it at your workstation!