Documentation Deployment

This guide explains how documentation is built and deployed for the Ocmonica project.

Overview

The Ocmonica documentation is built using MkDocs Material and automatically deployed to GitHub Pages using GitHub Actions.

Architecture

Deployment Overview

graph TB
    subgraph "Development"
        Dev[Developer]
        LocalBuild[Local Build & Test]
        Commit[Git Commit]
    end

    subgraph "Version Control"
        PR[Pull Request]
        Main[Main Branch]
    end

    subgraph "CI/CD Pipeline"
        Actions[GitHub Actions]
        Build[Build Job]
        Validate[Validation Job]
        Deploy[Deploy Job]
    end

    subgraph "Deployment Target"
        Pages[GitHub Pages]
        LiveDocs[Live Documentation Site]
    end

    Dev --> LocalBuild
    LocalBuild --> Commit
    Commit --> PR
    PR --> Actions
    Actions --> Build
    Actions --> Validate
    Build --> Validate
    Validate -->|Tests Pass| Main
    Main --> Actions
    Actions --> Deploy
    Deploy --> Pages
    Pages --> LiveDocs

    classDef dev fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef vcs fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef cicd fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef deploy fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px

    class Dev,LocalBuild,Commit dev
    class PR,Main vcs
    class Actions,Build,Validate,Deploy cicd
    class Pages,LiveDocs deploy

CI/CD Pipeline Detail

graph TB
    subgraph "Trigger Events"
        PushMain[Push to main<br/>docs/** changed]
        PushPR[Pull Request<br/>docs/** changed]
    end

    subgraph "Build Job"
        Checkout1[Checkout Code]
        SetupPy1[Setup Python 3.11]
        Cache1[Restore pip Cache]
        Install1[Install Dependencies<br/>requirements.txt]
        BuildDocs[mkdocs build --strict]
        Upload[Upload Artifact]
    end

    subgraph "Validation Job"
        Checkout2[Checkout Code]
        MarkdownLint[Markdown Lint<br/>Check Formatting]
        LinkCheck[Link Check<br/>Broken Links]
    end

    subgraph "Deploy Job"
        Download[Download Artifact]
        SetupPages[Setup GitHub Pages]
        DeployPages[Deploy to Pages]
        Verify[Verify Deployment]
    end

    Success[Deployment Complete<br/>Live at github.io]
    Preview[Preview Artifact<br/>Available in PR]

    PushMain --> Checkout1
    PushPR --> Checkout1
    PushPR --> Checkout2

    Checkout1 --> SetupPy1
    SetupPy1 --> Cache1
    Cache1 --> Install1
    Install1 --> BuildDocs
    BuildDocs -->|Success| Upload

    Checkout2 --> MarkdownLint
    MarkdownLint --> LinkCheck

    Upload -->|main branch| Download
    Upload -->|PR| Preview

    Download --> SetupPages
    SetupPages --> DeployPages
    DeployPages --> Verify
    Verify --> Success

    classDef trigger fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef build fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef validate fill:#fff9c4,stroke:#f57f17,stroke-width:2px
    classDef deploy fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef success fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px

    class PushMain,PushPR trigger
    class Checkout1,SetupPy1,Cache1,Install1,BuildDocs,Upload build
    class Checkout2,MarkdownLint,LinkCheck validate
    class Download,SetupPages,DeployPages,Verify deploy
    class Success,Preview success

GitHub Actions Workflows

Documentation Build & Deploy (docs.yml)

Triggers: - Push to main branch (with documentation changes) - Pull requests (with documentation changes)

Path filters: - docs/** - Documentation content - mkdocs.yml - MkDocs configuration - requirements.txt - Python dependencies - .github/workflows/docs.yml - Workflow file

Jobs:

1. Build Job
2. Checks out repository
3. Sets up Python 3.11 with pip caching
4. Installs dependencies from requirements.txt
5. Builds documentation with mkdocs build --strict --verbose

6. Uploads artifact for deployment (main) or preview (PR)

7. Deploy Job (main branch only)

8. Deploys built documentation to GitHub Pages
9. Updates live documentation site
10. Requires GitHub Pages to be enabled in repository settings

Build Time: ~1-2 minutes with caching

Documentation Validation (docs-validation.yml)

Triggers: - Pull requests (with markdown changes)

Path filters: - docs/**/*.md - Documentation files - *.md - Root markdown files (README, CONTRIBUTING, etc.)

Jobs:

1. Markdown Lint
2. Validates markdown formatting
3. Checks against .markdownlint.yaml rules

4. Reports style violations

5. Link Check

6. Validates internal links
7. Uses mkdocs build --strict to catch broken links
8. Fails if any links are broken

GitHub Pages Setup

Initial Configuration

1. Enable GitHub Pages:
2. Go to repository Settings → Pages
3. Under Source, select GitHub Actions

4. Click Save

5. Verify Deployment:

6. Go to Actions tab
7. Wait for first deployment to complete
8. Visit your documentation site at: https://<username>.github.io/<repository>/

Permissions

The workflow requires these permissions (automatically configured):

permissions:
  contents: read      # Read repository content
  pages: write        # Write to GitHub Pages
  id-token: write     # OIDC token for deployment

Local Development

Preview Documentation Locally

# Install dependencies
pip install -r requirements.txt

# Serve with live reload
mkdocs serve

# Open browser to http://127.0.0.1:8000

Build Documentation Locally

# Build static site
mkdocs build

# Build with strict mode (catches errors)
mkdocs build --strict

# Output is in site/ directory

Validate Documentation

# Check markdown formatting
docker run -v "$PWD:/workdir" davidanson/markdownlint-cli2 "docs/**/*.md"

# Or install locally
npm install -g markdownlint-cli2
markdownlint-cli2 "docs/**/*.md"

Troubleshooting

Build Failures

Error: "Strict mode: Broken link" - Check the error message for the broken link - Ensure all internal links use correct paths - Update or remove broken external links

Error: "Config file 'mkdocs.yml' not found" - Ensure mkdocs.yml exists in repository root - Check workflow path filters

Error: "Module not found" - Check requirements.txt includes all dependencies - Verify Python version compatibility (3.11+)

Deployment Issues

Pages not updating: - Check Actions tab for deployment status - Verify GitHub Pages is enabled and set to "GitHub Actions" - Check repository permissions

404 errors on site: - Ensure site_url in mkdocs.yml is correct - Check nav structure in mkdocs.yml - Verify file paths are relative to docs/ directory

Markdown Lint Failures

Line too long: - Configure .markdownlint.yaml to allow longer lines - Or break long lines (except in code blocks and URLs)

Inline HTML: - Add allowed HTML elements to .markdownlint.yaml - Or use markdown alternatives

Workflow Monitoring

Check Build Status

1. Actions Tab:
2. Go to repository Actions
3. Click on workflow run

4. View logs for each step

5. Pull Request Checks:

6. Documentation build status shows in PR checks

7. Click "Details" to view logs

8. Deployment Status:

9. Deployment shows in repository Environments section
10. View deployment history and URLs

Best Practices

1. Always test locally before pushing:

   mkdocs build --strict
   

2. Keep documentation in sync with code:

3. Update docs in the same PR as code changes

4. Use path filters to trigger builds only when needed

5. Use semantic commit messages:

   docs: add deployment guide
   docs(api): update REST API documentation
   fix(docs): correct broken link in architecture
   

6. Review documentation previews:

7. Download PR artifact to review changes

8. Check navigation and formatting

9. Monitor build times:

10. Use pip caching to speed up builds
11. Optimize large images or assets

Configuration Files

.github/workflows/docs.yml

Main workflow for building and deploying documentation.

.github/workflows/docs-validation.yml

Validation workflow for pull requests.

.markdownlint.yaml

Markdown linting rules and configuration.

mkdocs.yml

MkDocs configuration (theme, plugins, navigation).

requirements.txt

Python dependencies for documentation build.

Additional Resources

• MkDocs Documentation
• MkDocs Material Documentation
• GitHub Pages Documentation
• GitHub Actions Documentation
• Markdownlint Rules