Publishing Documentation¶

This guide explains how to publish and maintain the documentation site.

Overview¶

The documentation is built with MkDocs using the Material theme. It's automatically deployed to GitHub Pages when changes are pushed to the main branch.

Automatic Deployment¶

Documentation is automatically published via GitHub Actions when:

Changes are pushed to main branch affecting docs/ or mkdocs.yml
The workflow is manually triggered

The workflow file is located at .github/workflows/docs.yml.

Initial GitHub Pages Setup¶

If GitHub Pages isn't configured yet:

Go to your repository on GitHub
Navigate to Settings > Pages
Under Build and deployment:
Source: Select "GitHub Actions"
Save the settings

The next push to main with documentation changes will trigger deployment.

Local Development¶

Prerequisites¶

Install the required Python packages:

pip install -r docs/requirements.txt

Live Preview¶

Start a local development server with live reload:

mkdocs serve

Open http://127.0.0.1:8000 in your browser. Changes to documentation files are reflected immediately.

Build Locally¶

Build the static site without serving:

mkdocs build

The output is generated in the site/ directory (gitignored).

Strict Mode¶

Check for broken links and warnings:

mkdocs build --strict

This will fail if there are any warnings, useful for CI validation.

Manual Deployment¶

If you need to deploy manually (not recommended for normal use):

mkdocs gh-deploy

This builds the site and pushes to the gh-pages branch.

Prefer Automatic Deployment

Manual deployment bypasses CI checks. Use the automatic GitHub Actions workflow for production deployments.

Documentation Structure¶

docs/
├── index.md                    # Landing page
├── requirements.txt            # Python dependencies
├── stylesheets/
│   └── extra.css               # Custom styling
├── getting-started/            # Installation & setup
├── user-guide/                 # End-user documentation
├── architecture/               # Technical architecture
├── w3d-format/                 # W3D format specification
├── development/                # Developer guides
└── api/                        # API reference

Adding New Pages¶

Create a new .md file in the appropriate directory
Add the page to mkdocs.yml under the nav section:

nav:
  - Section Name:
    - section/index.md
    - New Page: section/new-page.md  # Add this

Preview locally with mkdocs serve
Commit and push to main

Writing Guidelines¶

Markdown Features¶

The Material theme supports extended Markdown:

Admonitions (callout boxes):

!!! note "Title"
    Content here

!!! warning
    Warning content

!!! tip
    Helpful tip

Code blocks with titles:

```python title="example.py"
def hello():
    print("Hello")
```

Tabbed content:

=== "Tab 1"
    Content for tab 1

=== "Tab 2"
    Content for tab 2

Mermaid diagrams:

```mermaid
graph LR
    A --> B --> C
```

Style Guide¶

Use sentence case for headings
Keep lines under 100 characters when practical
Use code blocks for all code, commands, and file paths
Include examples for complex features
Link to related documentation pages

Troubleshooting¶

Build Fails with Warnings¶

Run mkdocs build --strict locally to see warnings. Common issues:

Broken internal links (check file paths)
Missing pages listed in nav
Invalid YAML in mkdocs.yml

Pages Not Updating¶

Check GitHub Actions workflow status
Verify changes are on main branch
Clear browser cache or try incognito mode
GitHub Pages can take a few minutes to update

Local Server Won't Start¶

# Ensure dependencies are installed
pip install -r docs/requirements.txt

# Check for port conflicts
mkdocs serve -a 127.0.0.1:8001  # Use different port

Configuration Reference¶

Key settings in mkdocs.yml:

Setting	Purpose
`site_name`	Site title in header
`site_url`	Production URL (for sitemap)
`repo_url`	GitHub repository link
`theme.palette`	Color scheme settings
`nav`	Navigation structure
`plugins`	MkDocs plugins
`markdown_extensions`	Markdown feature extensions

See the MkDocs Material documentation for all available options.