Skip to content

MkDocs Extensions Guide#

This guide explains all the markdown extensions enabled in this documentation site and how to use them effectively.

Installation Required

Before using these extensions, install all required packages: MkDocs Installation Guide

Table of Contents Extensions#

toc - Table of Contents#

Automatically generates table of contents from page headings.

Configuration: 

- toc:
    permalink: "#"      # Adds clickable anchor links to headings
    toc_depth: 3        # Include h1, h2, h3 in TOC (excludes h4, h5, h6)

Usage: 

# Heading 1
## Heading 2
### Heading 3

Each heading automatically gets an anchor link you can click to get a direct URL.

Code Highlighting Extensions#

pymdownx.highlight - Syntax Highlighting#

Provides beautiful syntax highlighting for code blocks.

Example: 

def calculate_zone(temperature):
    """Calculate USDA hardiness zone from temperature."""
    if temperature < -60:
        return "1a"
    elif temperature < -55:
        return "1b"
    # ... more logic
    return "13b"

Features: - Line numbers with anchor_linenums: true - Line highlighting - Language-specific syntax coloring

pymdownx.inlinehilite - Inline Code Highlighting#

Highlight code within text: print("Hello") renders as syntax-highlighted inline code.

Example: The function def my_func(): does something important.

pymdownx.snippets - Code Snippet Inclusion#

Include code from external files directly into documentation.

Example:

From here you can also specify sections:

pymdownx.superfences - Advanced Code Blocks#

Enables nested code blocks and custom fences like Mermaid diagrams.

Diagram Support#

Mermaid Diagrams#

Create diagrams directly in markdown using Mermaid syntax.

Example - Flowchart: 

graph LR
    A[Gardener] --> B{Check Zone}
    B -->|Zone 6a| C[Select Plants]
    B -->|Zone 7b| D[Select Plants]
    C --> E[Add to Garden]
    D --> E

Example - Sequence Diagram: 

sequenceDiagram
    User->>System: Search for tomato
    System->>Database: Query plants
    Database-->>System: Return results
    System-->>User: Display plants

Example - Class Diagram: 

classDiagram
    class Plant {
        +String commonName
        +String scientificName
        +String hardinessZone
        +Boolean isDroughtTolerant
        +getPlantInfo()
    }
    class Profile {
        +User user
        +List plants
        +addPlant()
        +removePlant()
    }
    Profile --> Plant : contains

Supported Diagram Types: - Flowcharts (graph) - Sequence diagrams (sequenceDiagram) - Class diagrams (classDiagram) - State diagrams (stateDiagram) - Entity Relationship diagrams (erDiagram) - Gantt charts (gantt) - Pie charts (pie) - Git graphs (gitGraph)

Learn More: Mermaid Documentation

Content Organization Extensions#

pymdownx.tabbed - Tabbed Content#

Create tabbed content blocks for organizing related information.

Example: 

=== "Web Interface"
    Access the plant search from the main navigation menu.

=== "Mobile App"
    Tap the search icon in the bottom navigation bar.

=== "API"
    ```bash
    curl https://api.example.com/plants?zone=6a
    ```

Renders as:

Access the plant search from the main navigation menu.

Tap the search icon in the bottom navigation bar.

curl https://api.example.com/plants?zone=6a

Admonitions & Callouts#

admonition - Callout Boxes#

Create attention-grabbing callout boxes.

Available Types:

Note

This is a note - use for general information.

Tip

This is a tip - use for helpful suggestions.

Warning

This is a warning - use for important caveats.

Danger

This is a danger alert - use for critical warnings.

Example

This is an example - use for code examples or demonstrations.

Quote

This is a quote - use for citations or references.

Success

This is a success message - use for confirmations.

Information

This is an info box - use for supplementary information.

Question

This is a question - use for FAQs or clarifications.

Bug

This is a bug alert - use for known issues.

Syntax: 

!!! note "Custom Title"
    Content goes here.
    Can be multiple paragraphs.

Custom Plant Tip (with custom CSS): 

!!! plant-tip "Plant Tip"
    Tomatoes need 6-8 hours of full sun daily.

pymdownx.details - Collapsible Admonitions#

Make admonitions collapsible to save space.

Example: 

??? question "How do I determine my USDA zone?"
    Click here to expand and see the answer.

    Your USDA hardiness zone is based on your location's average annual minimum temperature.

Renders as:

How do I determine my USDA zone?

Click here to expand and see the answer.

Your USDA hardiness zone is based on your location's average annual minimum temperature.

Start Expanded: 

???+ tip "Pro Tip"
    This starts open but can be collapsed.

Table Extensions#

tables - Enhanced Tables#

Create beautiful, responsive tables.

Example: 

| Plant | Zone | Sun | Water |
|-------|------|-----|-------|
| Tomato | 3-11 | Full | Medium |
| Lettuce | 2-11 | Partial | High |
| Basil | 10-11 | Full | Medium |

Renders as:

Plant Zone Sun Water
Tomato 3-11 Full Medium
Lettuce 2-11 Partial High
Basil 10-11 Full Medium

Alignment: 

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Content      | Content        | Content       |

mkdocs-table-reader-plugin - Import Tables from External Files#

View this extension's documentation here. Learn how to use it to create reproducible reports via here.

Include tables directly from CSV, Excel, or other data files into your documentation.

NOTE: This was removed from the project since we did not want to work with the data but merely show the sheet.

Installation: 

uv add mkdocs-table-reader-plugin

Configuration in mkdocs.yml: 

plugins:
  - table-reader

Basic Usage - CSV Files: 

\{\{ read_csv('path/to/data.csv') \}\}

Basic Usage - Excel Files: 

\{\{ read_excel('path/to/spreadsheet.xlsx') \}\}

Read Specific Excel Sheet: 

\{\{ read_excel('path/to/spreadsheet.xlsx', sheet_name='Sheet1') \}\}

Advanced Options: 

<!-- Include only specific columns -->
\{\{ read_csv('data.csv', usecols=['Name', 'Zone', 'Type']) \}\}

<!-- Skip rows -->
\{\{ read_csv('data.csv', skiprows=2) \}\}

<!-- Use specific encoding -->
\{\{ read_csv('data.csv', encoding='utf-8') \}\}

<!-- Read Excel with specific range -->
\{\{ read_excel('data.xlsx', sheet_name='Plants', usecols='A:D') \}\}

Example - Decision Matrix: 

## Project Decisions

The following decision matrix was used to evaluate our options:

{{ read_excel('../../decisions/CESYS524_decision-matrix_kkeeton.xlsx') }}

Features: - Automatically converts CSV/Excel to markdown tables - Supports pandas DataFrame operations - Updates automatically when source files change - No need to manually maintain duplicate table data - Supports filtering, column selection, and formatting

Use Cases: - Decision matrices and trade-off analyses - Quality Function Deployment (QFD) matrices - FMEA (Failure Mode and Effects Analysis) tables - N-squared charts and interface matrices - Any tabular data stored in external files

Learn More: mkdocs-table-reader-plugin Documentation

Styling Extensions#

attr_list - Add CSS Classes#

Add custom CSS classes and attributes to elements.

Example: 

![Plant Image](path/to/image.jpg){ .plant-image }

{.zone-badge}
Zone 6a

md_in_html - Markdown Inside HTML#

Use markdown syntax inside HTML blocks.

Example: 

<div class="feature-card">

## Feature Title

- Markdown list item
- Another item

</div>

pymdownx.emoji - Emoji Support#

Use emojis via shortcodes.

Examples: - :seedling: → 🌱 - :sunflower: → 🌻 - :cactus: → 🌵 - :herb: → 🌿 - :bouquet: → 💐 - :cherry_blossom: → 🌸

Search emojis: Emoji Cheat Sheet

Task List Extensions#

pymdownx.tasklist - Interactive Checkboxes#

Create task lists with checkboxes.

Example: 

- [x] Choose planting location
- [x] Test soil pH
- [ ] Purchase seeds
- [ ] Plant seeds
- [ ] Water regularly

Renders as:

  • Choose planting location
  • Test soil pH
  • Purchase seeds
  • Plant seeds
  • Water regularly

List Extensions#

def_list - Definition Lists#

Create glossary-style definition lists.

Example: 

USDA Hardiness Zone
:   A geographic area defined by average annual minimum temperature, used to determine which plants can survive in a location.

Full Sun
:   6 or more hours of direct sunlight per day.

Partial Shade
:   3-6 hours of direct sunlight per day.

Renders as:

USDA Hardiness Zone
A geographic area defined by average annual minimum temperature, used to determine which plants can survive in a location.
Full Sun
6 or more hours of direct sunlight per day.
Partial Shade
3-6 hours of direct sunlight per day.

Reference Extensions#

abbr - Abbreviations#

Define abbreviations with tooltips.

Example: 

The USDA defines plant hardiness zones.

*[USDA]: United States Department of Agriculture

When you hover over "USDA", you'll see the full definition.

footnotes - Footnotes#

Add footnotes to content.

Example: 

Plants in zone 6a can survive temperatures down to -10°F[^1].

[^1]: USDA Plant Hardiness Zone Map, 2012 revision

Renders as:

Plants in zone 6a can survive temperatures down to -10°F1.

Typography Extensions#

pymdownx.smartsymbols - Smart Symbols#

Automatically converts text to proper symbols.

Conversions: - (c) → © - (r) → ® - (tm) → ™ - c/o → ℅ - +/- → ± - --> → → - <-- → ← - <--> → ↔ - =/= → ≠

pymdownx.keys - Keyboard Keys#

Display keyboard shortcuts beautifully.

Example: 

Press ++ctrl+alt+delete++ to restart.
Press ++cmd+s++ to save.

Renders as:

Press Ctrl+Alt+Del to restart.

Review Extensions#

pymdownx.critic - Track Changes#

Mark up content for review with track-changes style markup.

Syntax: 

This is deleted text.
This is added text.
This is oldnew text.
This is highlighted text.
This is a comment

Renders as:

This is deleted text. This is added text. This is oldnew text. This is highlighted text. This is a comment

Math Extensions#

pymdownx.arithmatex - Mathematical Expressions#

Write mathematical formulas using LaTeX syntax.

Inline Math: 

The area of a circle is $A = \pi r^2$.

Block Math: 

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Example - Growing Calculations: 

Plant spacing: $S = \frac{L}{n-1}$ where L is length and n is number of plants.

Best Practices#

When to Use Each Extension#

Admonitions: - Use note for general information - Use warning for important caveats - Use tip for helpful suggestions - Use example for code demonstrations

Diagrams: - Use flowcharts for process flows - Use sequence diagrams for API interactions - Use class diagrams for data models - Use entity-relationship diagrams for database schemas

Tabs: - Use for multiple implementations (web vs mobile) - Use for different user roles (admin vs user) - Use for multiple code examples (Python vs JavaScript)

Tables: - Use for structured data (plant characteristics) - Use for comparison (feature matrices) - Keep tables simple - complex tables are hard to read on mobile

Accessibility Considerations#

  1. Always provide alt text for images: 

    ![USDA Hardiness Zone Map showing zones 1a through 13b](path/to/image.jpg)

  2. Use semantic heading structure:

  3. Don't skip heading levels (h1 → h3)

  4. Use h1 only once per page

  5. Make link text descriptive:

  6. ❌ [Click here](link) for more information

  7. ✅ [Learn about USDA zones](link) for detailed information

  8. Use proper table headers: 

    | Plant Name | Zone | Spacing |
|------------|------|---------|
| Tomato     | 3-11 | 24-36"  |

Image Processing (Quick Reference)#

This documentation uses two plugins for optimal image handling.

Automatic Image Optimization#

All images are automatically compressed during build - no special syntax needed.

Just add images normally: 

![Plant Diagram](img/plant-structure.png)

The optimize plugin automatically: - Compresses PNG/JPG files (30-70% size reduction) - Strips metadata - Generates WebP versions - Caches results for faster rebuilds

Click-to-Zoom Lightbox#

All images automatically get click-to-zoom functionality.

Basic usage (auto-enabled): 

![Tomato Plant](img/tomato.jpg)

Click image to open lightbox. Use arrow keys or swipe to navigate.

Disable lightbox for specific images: 

![Small Icon](img/icon.png){ .skip-lightbox }

Create image gallery: 

![Stage 1](img/stage1.jpg)
![Stage 2](img/stage2.jpg)
![Stage 3](img/stage3.jpg)

Multiple images become a navigable gallery. Click any image, then use ← → arrows or swipe.

Keyboard shortcuts in lightbox: - ← / → - Navigate gallery - Esc - Close - + / - - Zoom in/out

Installation & Configuration

For setup instructions, system dependencies, and troubleshooting, see: Image Processing Setup Guide

Custom Extensions (Project-Specific)#

Zone Badges#

Use custom CSS class for zone badges:

<span class="zone-badge">Zone 6a</span>

Status Badges#

Use for requirement/specification status:

<div class="status-badge draft">Draft</div>
<div class="status-badge review">In Review</div>
<div class="status-badge approved">Approved</div>
<div class="status-badge implemented">Implemented</div>

Feature Cards#

Use for highlighting features:

<div class="feature-card">

## Plant Search

Search thousands of plants by name, zone, characteristics, and more.

</div>

Additional Resources#

Need Help?#

If you're unsure which extension to use, refer to this decision tree:

graph TD
    A[What do you need?] --> B{Content Type}
    B -->|Diagram| C[Use Mermaid]
    B -->|Code| D[Use highlight/superfences]
    B -->|Important Info| E[Use admonition]
    B -->|Organize Options| F[Use tabs]
    B -->|Structured Data| G[Use table]
    B -->|Definition| H[Use def_list]
    B -->|Track Changes| I[Use critic]

Last Updated: 2025-12-12 Maintained By: Gardening App Documentation Team

  1. USDA Plant Hardiness Zone Map, 2012 revision ↩