blackroad-operating-system/codex-docs/DEPLOY_DOCS.md

Documentation Deployment Guide

This guide explains how to build, test, and deploy the BlackRoad OS documentation (Codex).

---

Prerequisites

• Python 3.8+
• pip (Python package manager)
• Git
• GitHub repository access

---

Quick Start

1. Install Dependencies

# Navigate to codex-docs directory
cd codex-docs

# Install MkDocs, Material theme, and Minify plugin
pip install mkdocs mkdocs-material pymdown-extensions mkdocs-minify-plugin

2. Test Locally

# Serve documentation locally
mkdocs serve

# Access at: http://localhost:8000
# Docs auto-reload on file changes

3. Build Documentation

# Build static site (strict mode catches errors)
mkdocs build --strict

# Output in: codex-docs/site/

4. Deploy to GitHub Pages

Automatic (Recommended):

Push changes to main branch. GitHub Actions workflow automatically builds and deploys.

Manual:

# Deploy to gh-pages branch
mkdocs gh-deploy

# This creates/updates the gh-pages branch with built site

---

Configuration

MkDocs Configuration

File: codex-docs/mkdocs.yml

Key settings:

site_name: BlackRoad OS Codex
site_url: https://docs.blackroad.systems
repo_url: https://github.com/blackboxprogramming/BlackRoad-Operating-System

theme:
  name: material
  palette:
    scheme: slate  # Dark mode
    primary: deep purple
    accent: purple

nav:
  - Home: index.md
  - Architecture: architecture/
  - API Reference: api/
  - Guides: guides/
  - Agents: agents/
  - Contributing: contributing.md

Material Theme Customization

Custom CSS: codex-docs/docs/stylesheets/extra.css

/* Add custom styles here */
.md-header {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

---

GitHub Pages Setup

Step 1: Enable GitHub Pages

1. Go to repository Settings → Pages
2. Source:
   • Branch: gh-pages
   • Folder: / (root)
3. Click "Save"

Step 2: Configure Custom Domain

In GitHub:

1. Settings → Pages → Custom domain
2. Enter: docs.blackroad.systems
3. ✅ Enforce HTTPS
4. Save

In Cloudflare DNS:

Add CNAME record:

Type	Name	Target	Proxy
CNAME	docs	blackboxprogramming.github.io	✅ Proxied

Step 3: Wait for DNS Propagation

# Check DNS
dig docs.blackroad.systems

# Check HTTPS
curl -I https://docs.blackroad.systems

Propagation time: 5-10 minutes

---

GitHub Actions Workflow

File: .github/workflows/docs-deploy.yml

Workflow triggers:

• Push to main branch (if codex-docs/ changed)
• Manual dispatch (Actions tab → Run workflow)

Steps:

1. Checkout code
2. Install Python 3.11
3. Install MkDocs + Material + pymdown-extensions
4. Build with mkdocs build --strict
5. Deploy to gh-pages branch

Manual Workflow Trigger

1. Go to repository → Actions
2. Select "Deploy Documentation" workflow
3. Click "Run workflow"
4. Select branch: main
5. Click "Run workflow"

---

Writing Documentation

File Structure

codex-docs/
├── mkdocs.yml              # Configuration
├── docs/                   # Markdown files
│   ├── index.md            # Homepage
│   ├── architecture/       # Architecture docs
│   ├── api/                # API reference
│   ├── guides/             # User guides
│   ├── agents/             # Agent docs
│   └── contributing.md     # Contributing guide
└── site/                   # Built site (gitignored)

Adding a New Page

1. Create markdown file in docs/
2. Add to navigation in mkdocs.yml:

nav:
  - New Section:
      - Page Title: path/to/file.md

3. Test locally: mkdocs serve
4. Commit and push

Markdown Extensions

Admonitions (callouts):

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

!!! warning
    This is a warning.

!!! tip
    This is a tip.

Code Blocks with syntax highlighting:

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

Tabs:

=== "Python"
    ```python
    print("Hello")
    ```

=== "JavaScript"
    ```javascript
    console.log("Hello");
    ```

Diagrams (Mermaid):

```mermaid
graph LR
    A[Start] --> B[Process]
    B --> C[End]
```

---

Troubleshooting

Issue: Build fails with "Strict mode"

Cause: Broken links or missing files

Fix:

# Build with verbose output
mkdocs build --strict --verbose

# Check error message for specific issue
# Common issues:
# - Broken internal links
# - Missing images
# - Invalid YAML in frontmatter

Issue: Changes not appearing

Check:

1. Workflow ran successfully (GitHub Actions)
2. gh-pages branch updated (check commit time)
3. Hard refresh browser (Ctrl+F5)
4. DNS cache cleared

Debug:

# Check workflow status
gh run list --workflow=docs-deploy.yml

# View workflow logs
gh run view <run-id> --log

Issue: Custom domain not working

Check:

1. CNAME record in Cloudflare:

   dig docs.blackroad.systems
   # Should return: blackboxprogramming.github.io
   

2. GitHub Pages settings:

   • Custom domain: docs.blackroad.systems
   • Enforce HTTPS: ✅ enabled

3. Wait 5-10 minutes for DNS propagation

Issue: CSS not loading

Check:

1. extra_css in mkdocs.yml points to correct file
2. CSS file exists in docs/stylesheets/
3. Hard refresh browser (Ctrl+Shift+R)

---

Best Practices

Documentation Writing

• Clear titles: Use descriptive H1 headings
• TOC: MkDocs auto-generates table of contents
• Code examples: Always include working examples
• Screenshots: Use when helpful, but keep file size < 500KB
• Links: Use relative links for internal pages

Maintenance

• Update on feature changes: New API endpoints, config options
• Version docs: (future) Use mike for versioning
• Test locally: Always mkdocs serve before pushing
• Review workflow: Check Actions tab after pushing

Performance

• Image optimization: Use compressed images (PNG/WebP)
• Lazy loading: Material theme handles this
• CDN: GitHub Pages + Cloudflare provide global CDN

---

Advanced Features

Search Configuration

File: mkdocs.yml

plugins:
  - search:
      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'

Analytics (Future)

File: mkdocs.yml

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX  # Replace with actual ID

Versioning (Future - Phase 2+)

Use mike for version management:

# Install mike
pip install mike

# Deploy v1.0
mike deploy 1.0 latest -u

# Set default version
mike set-default latest

---

Deployment Checklist

Before deploying:

• All markdown files render correctly locally
• No broken links (mkdocs build --strict passes)
• Navigation structure is logical
• Code examples are tested
• Images are optimized
• Frontmatter is valid (if used)

After deploying:

• Workflow completed successfully (GitHub Actions)
• Site accessible at https://docs.blackroad.systems
• Search works
• Navigation works
• Mobile responsive (test on phone)
• SSL enabled (green padlock)

---

Resources

MkDocs

• Documentation: https://www.mkdocs.org
• Material Theme: https://squidfunk.github.io/mkdocs-material/
• Extensions: https://facelessuser.github.io/pymdown-extensions/

GitHub Pages

• Documentation: https://docs.github.com/en/pages
• Custom domains: https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site

Markdown

• CommonMark Spec: https://commonmark.org
• GitHub Flavored Markdown: https://github.github.com/gfm/

---

Support

• Issues: Report documentation issues on GitHub Issues
• Discussions: Use GitHub Discussions for questions
• Pull Requests: Contributions welcome!

---

Where AI meets the open road. 🛣️

Documentation deployment guide for BlackRoad OS Codex