MkDocs Documentation Guide¶

This project uses MkDocs with the Material theme for documentation. This guide covers our specific configuration, extensions, and how to use them.

Quick Start¶

# Serve docs locally with live reload
just documentation::serve

# Build static site
just documentation::build

# Open docs in browser
just documentation::open

Theme Configuration¶

We use Material for MkDocs with dark mode as the default. Users can toggle between dark and light modes using the sun/moon icon in the header.

Color scheme: Deep purple primary with purple accent.

Markdown Extensions¶

Code Blocks¶

Syntax Highlighting¶

Standard fenced code blocks with language hints:

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

Line Numbers and Highlighting¶

```python linenums="1" hl_lines="2 3"
def hello():
    # These lines are highlighted
    print("Hello!")
```

Code Annotations¶

Add numbered annotations that expand on hover:

```python
def process(data):  # (1)!
    return data.strip()  # (2)!
```

1. This function processes input data
2. Removes leading/trailing whitespace

Inline Code Highlighting¶

Use print("inline") for inline syntax highlighting:

Use `#!python print("inline")` for inline code with highlighting.

Tabbed Content¶

Create tabs for platform-specific or alternative content:

=== "macOS"

    ```bash
    ~/Library/Application Support/FreeCAD/Macro/
    ```

=== "Linux"

    ```bash
    ~/.local/share/FreeCAD/Macro/
    ```

=== "Windows"

    ```bash
    %APPDATA%/FreeCAD/Macro/
    ```

Renders as:

macOSLinuxWindows

~/Library/Application Support/FreeCAD/Macro/

~/.local/share/FreeCAD/Macro/

%APPDATA%/FreeCAD/Macro/

Admonitions (Call-outs)¶

Create styled call-out boxes:

!!! note "Optional Title"
    This is a note admonition.

!!! warning
    This is a warning without a custom title.

!!! danger "Critical"
    This is a danger/error admonition.

!!! tip
    This is a tip admonition.

!!! info
    This is an info admonition.

!!! example
    This is an example admonition.

Collapsible admonitions:

??? note "Click to expand"
    This content is hidden by default.

???+ note "Expanded by default"
    This content is visible but can be collapsed.

Available types: note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote

Task Lists¶

Create checkbox lists:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Renders as:

Completed task
Incomplete task
Another task

Keyboard Keys¶

Style keyboard shortcuts:

Press ++ctrl+c++ to copy.
Press ++cmd+shift+p++ on macOS.
Press ++enter++ to confirm.

Renders as: Press Ctrl+C to copy.

Common keys: ctrl, alt, shift, cmd, enter, tab, esc, backspace, delete, up, down, left, right, f1-f12

Text Formatting¶

Highlighting¶

==This text is highlighted==

Renders as: This text is highlighted

Subscript and Superscript¶

H~2~O (subscript)
x^2^ (superscript)

Renders as: H₂O and x²

Strikethrough¶

~~deleted text~~

Renders as: ~~deleted text~~

Critic Markup (for diffs/reviews)¶

deleted
added
oldnew
highlighted
comment

Definition Lists¶

Term 1
:   Definition for term 1

Term 2
:   Definition for term 2
:   Can have multiple definitions

Renders as:

Term 1: Definition for term 1
Term 2: Definition for term 2; Can have multiple definitions

Footnotes¶

This needs a citation[^1].

[^1]: This is the footnote content.

Mermaid Diagrams¶

Create diagrams using Mermaid syntax:

```mermaid
graph LR
    A[MCP Client] --> B[Robust MCP Server]
    B --> C[FreeCAD Bridge]
    C --> D[FreeCAD]
```

Renders as:

graph LR
    A[MCP Client] --> B[Robust MCP Server]
    B --> C[FreeCAD Bridge]
    C --> D[FreeCAD]

Supported diagram types: flowchart, sequence, class, state, ER, gantt, pie, journey

Plugins¶

Git Revision Date¶

Pages automatically show "Last updated X ago" at the bottom. No action needed.

All images are automatically zoomable. Click any image to open in a lightbox overlay.

To exclude an image from lightbox:

![Image](path/to/image.png){ .off-glb }

Minification¶

HTML is automatically minified in production builds. No action needed.

Search¶

Full-text search is enabled. Features:

Search suggestions as you type
Search result highlighting
Shareable search URLs

Macros Plugin¶

Custom Delimiters¶

Important

We use custom delimiters to avoid conflicts with Python dict literals in code blocks.

Variables: { {@ and @} }
Blocks: {% @ and @ %}

Standard Jinja2 { { } } syntax will NOT work.

Using Variables¶

Variables are defined in docs/variables.yaml:

# docs/variables.yaml
project_name: FreeCAD Robust MCP Suite
package_name: freecad-robust-mcp
xmlrpc_port: 9875
socket_port: 9876

Use in Markdown:

The default XML-RPC port is 9875.
Install with: `pip install freecad-robust-mcp`

Available Variables¶

Variable	Value	Description
`project_name`	FreeCAD Robust MCP Suite	Display name
`package_name`	freecad-robust-mcp	PyPI package name
`docker_image`	spkane/freecad-robust-mcp	Docker image
`xmlrpc_port`	9875	XML-RPC server port
`socket_port`	9876	Socket server port
`paths.macos.macro`	~/Library/...	macOS macro path
`paths.linux.macro`	~/.local/share/...	Linux macro path
`paths.windows.macro`	%APPDATA%/...	Windows macro path

Built-in Macros¶

Current time: 2026-02-04 07:29:24.497994
Page URL: development/mkdocs-guide/

API Documentation (mkdocstrings)¶

Auto-generate API docs from Python docstrings:

::: freecad_mcp.server
    options:
      show_source: true
      heading_level: 3

This renders the module's docstrings, classes, and functions automatically.

Options:

show_source: true - Show source code
heading_level: 3 - Start headings at h3
members: [func1, func2] - Only show specific members
filters: ["!^_"] - Exclude private members

Features Enabled¶

Instant navigation - Pages load without full refresh
Navigation tabs - Top-level sections as tabs
Section index pages - Click section to see overview
Back to top - Button appears when scrolling
Table of contents - Follows scroll position

Images¶

Basic Image¶

![Alt text](path/to/image.png)

Image with Caption¶

<figure markdown>
  ![Alt text](path/to/image.png)
  <figcaption>This is the caption</figcaption>
</figure>

Image Alignment¶

![Image](image.png){ align=left }
![Image](image.png){ align=right }

Image Size¶

![Image](image.png){ width="300" }

Links¶

Internal Links¶

[Installation Guide](../getting-started/installation.md)
[Config section](configuration.md#environment-variables)

External Links¶

External links automatically open in new tab (Material theme default).

[FreeCAD](https://www.freecad.org/)

Tables¶

Standard Markdown tables with sorting enabled:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

File Structure¶

docs/
├── index.md                 # Home page
├── variables.yaml           # Macros variables
├── overrides/               # Theme customizations
│   └── .gitkeep
├── assets/                  # Images, favicon, etc.
├── getting-started/
│   ├── installation.md
│   ├── configuration.md
│   └── quickstart.md
├── guide/
│   └── ...
├── api/
│   └── ...
└── development/
    ├── contributing.md
    ├── architecture.md
    ├── releasing.md
    └── mkdocs-guide.md      # This file

Common Tasks¶

Adding a New Page¶

Create the markdown file in the appropriate directory
Add to nav: section in mkdocs.yaml

Adding Redirects¶

If you move/rename a page, add a redirect in mkdocs.yaml:

plugins:
  - redirects:
      redirect_maps:
        'old-page.md': 'new-location/new-page.md'

Custom CSS¶

Add custom styles in docs/overrides/stylesheets/extra.css and reference in mkdocs.yaml:

extra_css:
  - overrides/stylesheets/extra.css

Custom JavaScript¶

Add scripts in docs/overrides/javascripts/extra.js and reference in mkdocs.yaml:

extra_javascript:
  - overrides/javascripts/extra.js

Troubleshooting¶

Macros Not Rendering¶

Remember to use custom delimiters: {{ variable }} not {{ variable }}.

Git Revision Date Warnings¶

New files not yet committed will show warnings. Commit the file to fix.

Build Errors¶

# Check for syntax errors
uv run mkdocs build --strict

# Verbose output
uv run mkdocs build -v

Serve Not Auto-Reloading¶

Some changes (like mkdocs.yaml) require restarting the server.

MkDocs Documentation Guide¶

Quick Start¶

Theme Configuration¶

Markdown Extensions¶

Code Blocks¶

Syntax Highlighting¶

Line Numbers and Highlighting¶

Code Annotations¶

Inline Code Highlighting¶

Tabbed Content¶

Admonitions (Call-outs)¶

Task Lists¶

Keyboard Keys¶

Text Formatting¶

Highlighting¶

Subscript and Superscript¶

Strikethrough¶

Critic Markup (for diffs/reviews)¶

Definition Lists¶

Footnotes¶

Mermaid Diagrams¶

Plugins¶

Git Revision Date¶

Image Lightbox (GLightbox)¶

Minification¶

Search¶

Macros Plugin¶

Custom Delimiters¶

Using Variables¶

Available Variables¶

Built-in Macros¶

API Documentation (mkdocstrings)¶

Navigation¶

Features Enabled¶

Images¶

Basic Image¶

Image with Caption¶

Image Alignment¶

Image Size¶

Links¶

Internal Links¶

External Links¶

Tables¶

File Structure¶

Common Tasks¶

Adding a New Page¶

Adding Redirects¶

Custom CSS¶

Custom JavaScript¶

Troubleshooting¶

Macros Not Rendering¶

Git Revision Date Warnings¶

Build Errors¶

Serve Not Auto-Reloading¶

Reference Links¶