How to Use MkDocs for SyRF Documentation¶

Overview¶

This guide explains how to use MkDocs to build and maintain the SyRF documentation site. MkDocs generates a beautiful, searchable static site from the Markdown files in the /docs/ directory.

Prerequisites¶

Python 3.10+ installed
pip package manager
Basic knowledge of Markdown

Installation¶

1. Install MkDocs and Dependencies¶

# From the repository root
pip3 install --user -r requirements.txt

This installs:

MkDocs (documentation generator)
Material for MkDocs (Material Design theme)
mkdocs-git-revision-date-localized-plugin (shows last updated dates)
mkdocs-minify-plugin (optimizes HTML/CSS/JS)
mike (for versioning, optional)
pymdown-extensions (enhanced Markdown features)

2. Verify Installation¶

python3.10 -m mkdocs --version

You should see output like: mkdocs, version 1.6.1

Local Development¶

Building the Site¶

Generate the static HTML site:

# Build without strict mode (allows warnings)
python3.10 -m mkdocs build

# Build with strict mode (fails on warnings)
python3.10 -m mkdocs build --strict

The generated site is placed in the /_docs_build/ directory (which is git-ignored). The underscore prefix makes it clear this is a build artifact, and the name clearly indicates it's documentation-related.

Serving Locally (Live Reload)¶

Preview the documentation site locally with automatic live reload (equivalent to ng serve for Angular):

Simple Commands (Cross-Platform):

# Linux/Mac - Using Makefile
make docs-serve

# Linux/Mac - Using shell script
./docs-serve.sh

# Windows - Using batch file
docs-serve.bat

# Or directly with Python (all platforms)
python3.10 -m mkdocs serve

This starts a local development server at http://127.0.0.1:8000/.

Features:

✅ Live reload - Automatically rebuilds and refreshes browser on file save
✅ Fast rebuilds - Only rebuilds changed pages
✅ No manual refresh needed

Options:

# Serve on a different port
python3.10 -m mkdocs serve -a localhost:8080

# Serve with strict mode (fails on warnings)
python3.10 -m mkdocs serve --strict

# Serve and make accessible on network
python3.10 -m mkdocs serve -a 0.0.0.0:8000

Configuration¶

The MkDocs configuration is in /mkdocs.yml. Key sections:

Site Metadata¶

site_name: SyRF Documentation
site_description: Comprehensive documentation for the SyRF monorepo
site_url: https://github.com/camaradesuk/syrf
repo_url: https://github.com/camaradesuk/syrf

Theme Configuration¶

We use the Material for MkDocs theme with:

Dark/light mode toggle
Navigation tabs
Instant navigation
Code copy buttons
Search with suggestions

The nav: section in mkdocs.yml defines the site structure:

nav:
  - Home:
    - index.md
    - Documentation Framework: README.md
  - Architecture:
    - architecture/index.md
    - Dependency Map: architecture/dependency-map.md
  # ... more sections

Important: Files not listed in nav: will still be built but won't appear in the navigation menu.

Plugins¶

Active plugins:

search: Full-text search with custom separators
tags: Document tagging system
git-revision-date-localized: Shows creation and update dates from git history

Markdown Extensions¶

We have many extensions enabled for enhanced Markdown features:

Admonitions: Callout boxes (notes, warnings, tips)
Code highlighting: Syntax highlighting with line numbers
Tables: GitHub-flavored tables
Mermaid diagrams: Embedded diagrams
Task lists: Checkboxes in lists
And many more...

See PyMdown Extensions for full documentation.

Writing Documentation¶

Adding a New Document¶

Create the Markdown file in the appropriate /docs/ subdirectory:

# Example: Create a new how-to guide
touch docs/how-to/deploy-to-production.md

Add YAML frontmatter (required by our documentation framework):

---
type: How-To
status: Draft
created: 2025-11-11
updated: 2025-11-11
author: Your Name
tags:
  - deployment
  - production
---

Write content using Markdown
Add to navigation in mkdocs.yml:

- How-To Guides:
    - how-to/index.md
    - Deploy to Production: how-to/deploy-to-production.md

Test locally:

python3.10 -m mkdocs serve

Using Admonitions¶

Create callout boxes for notes, warnings, tips, etc.:

!!! note
    This is a note admonition.

!!! warning
    This is a warning admonition.

!!! tip "Custom Title"
    This is a tip with a custom title.

??? example "Collapsible Example"
    This admonition starts collapsed.

Code Blocks with Syntax Highlighting¶

```bash
# This is a bash code block
mkdocs serve
```

```python
def hello_world():
    print("Hello, World!")
```

```csharp linenums="1"
// C# with line numbers
public class Example {
    public static void Main() {
        Console.WriteLine("Hello!");
    }
}
```

Mermaid Diagrams¶

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
```

Internal Links¶

Link to other documentation pages:

[See Architecture](../architecture/system-overview.md)
[ADR-001](../decisions/ADR-001-ci-cd-approach.md)

GitHub Pages Deployment¶

Automatic Deployment¶

The documentation is automatically deployed to GitHub Pages when:

Changes are pushed to the master branch
Files in /docs/, mkdocs.yml, or requirements.txt are modified

The workflow is defined in .github/workflows/docs.yml.

Manual Deployment¶

Trigger a manual deployment:

# Via GitHub CLI
gh workflow run docs.yml

# Or via GitHub web UI:
# Actions → Deploy Documentation → Run workflow

Viewing the Published Site¶

After deployment completes (usually 2-3 minutes), the site will be available at: https://camaradesuk.github.io/syrf/

GitHub Pages Configuration¶

To enable GitHub Pages for the first time:

Go to repository Settings → Pages
Set Source to "GitHub Actions"
Save (no branch selection needed)

The workflow handles the rest automatically.

Quick Reference Commands¶

Using Makefile (Linux/Mac/WSL)¶

make docs-install    # Install MkDocs and dependencies
make docs-serve      # Build and serve with live reload
make docs-build      # Build static site
make docs-clean      # Remove build artifacts

Using Shell Scripts¶

# Linux/Mac/WSL
./docs-serve.sh      # Build and serve with live reload

# Windows
docs-serve.bat       # Build and serve with live reload

Direct Python Commands¶

# Install dependencies
python3.10 -m pip install --user -r requirements.txt

# Serve with live reload (recommended for development)
python3.10 -m mkdocs serve

# Build static site
python3.10 -m mkdocs build

# Build with strict mode (catch all warnings)
python3.10 -m mkdocs build --strict

Common Tasks¶

Edit /mkdocs.yml and modify the nav: section:

nav:
  - Home: index.md
  - Architecture:
      - architecture/index.md
      - New Page: architecture/new-page.md

Change Theme Colors¶

Edit /mkdocs.yml:

theme:
  palette:
    - scheme: default
      primary: blue  # Change from 'indigo'
      accent: blue

Add Custom CSS¶

Edit /docs/stylesheets/extra.css
Rebuild the site

Custom CSS is automatically included via the extra_css: configuration.

Add Custom JavaScript¶

Edit /docs/javascripts/extra.js
Rebuild the site

Custom JavaScript is automatically included via the extra_javascript: configuration.

Troubleshooting¶

"Command not found: mkdocs"¶

Solution: Use python3.10 -m mkdocs instead of mkdocs directly, or add ~/.local/bin to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Build Warnings About Broken Links¶

Check the warning messages and fix broken links:

Use relative paths: ../architecture/file.md
Ensure linked files exist in /docs/
Don't link to files outside /docs/ (they won't be included)

Strict Mode Fails¶

If mkdocs build --strict fails:

Review all WARNING messages
Fix broken links and missing files
Update navigation to include all pages

The GitHub Actions workflow uses strict mode, so all warnings must be resolved before deployment.

Site Not Updating on GitHub Pages¶

Check the Actions tab for deployment status
Verify the workflow completed successfully
Clear browser cache
Wait a few minutes (CDN propagation)

Advanced Features¶

Multi-language Support¶

Material for MkDocs supports multiple languages. To add language switcher:

extra:
  alternate:
    - name: English
      link: /en/
      lang: en
    - name: Español
      link: /es/
      lang: es

Site Analytics¶

To add Google Analytics:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

Versioning with Mike¶

Deploy multiple versions of the docs:

# Deploy version 1.0
mike deploy 1.0 latest
mike set-default latest

# Deploy version 2.0
mike deploy 2.0 latest

This requires additional GitHub Pages configuration.

Best Practices¶

Always use YAML frontmatter (required by our documentation framework)
Test locally before pushing with mkdocs serve
Use relative links for internal documentation
Add new pages to navigation in mkdocs.yml
Fix all warnings before merging to master
Keep mkdocs.yml organized and commented
Use admonitions for important notes and warnings
Include code examples with syntax highlighting

Resources¶

MkDocs Documentation: https://www.mkdocs.org/
Material for MkDocs: https://squidfunk.github.io/mkdocs-material/
PyMdown Extensions: https://facelessuser.github.io/pymdown-extensions/
Markdown Guide: https://www.markdownguide.org/

Documentation Framework - SyRF documentation structure
Feature Planning Workflow - How to document features
CI/CD Workflow - Automated deployments

Last updated: 2025-11-11 (auto-generated by git-revision-date-localized plugin)