Contributing to Documentation¶

Build Locally¶

1. Install dependencies¶

cd docs
uv sync

2. Serve documentation locally¶

uv run mkdocs serve

Visit http://127.0.0.1:8000 in your browser.

3. Stop the server¶

Press Ctrl+C to stop the development server.

Adding New Pages¶

1. Create markdown file¶

Create a new .md file in docs/docs/ with your content:

# My New Page

## Section 1

Content here...

## Section 2

More content...

Edit mkdocs.yml and add your page to the nav section:

nav:
  - Home: index.md
  - My New Page: my-new-page.md
  - Other Page: other.md

3. Commit and push¶

git add docs/
git commit -m "docs: add page about topic"
git push origin docs/architecture-analysis

The GitHub Actions workflow will automatically build and deploy.

Style Guide¶

Headings¶

Use proper heading hierarchy:

# Top level (page title)

## Section heading

### Subsection heading

#### Detail heading (rarely needed)

Code Blocks¶

Always specify the language:

def example():
    return "Hello, World!"

echo "Shell command"

const example = () => "Hello, World!";

Cross-references¶

Link to related pages:

See [Quick Reference](01-quick-reference.md) for an overview.

Notes and Callouts¶

Use admonitions for emphasis:

!!! note "Important"
    This is an important point.

!!! warning "Caution"
    Be careful with this.

!!! tip "Pro Tip"
    Here's a helpful suggestion.

Renders as:

Important

This is an important point.

Building for Production¶

To build the static site without serving:

cd docs
uv run mkdocs build

Output goes to docs/site/. This directory is excluded from version control.

Deployment¶

Merging to main or docs/architecture-analysis branches triggers automatic deployment via GitHub Actions.

Questions? Check the Material for MkDocs documentation.