Documentation System¶

Overview¶

The Rose documentation is built using MkDocs with the Material theme. It is automatically deployed to Cloudflare Pages on every push to the develop or main branches.

Deployment Environments¶

Trigger	Git Branch	Environment	Cloudflare Branch	Domain
Push	`develop`	test	test	docstest.userose.ai
Push	`main`	production	main	docs.userose.ai
Manual dispatch "test"	any	test	test	docstest.userose.ai
Manual dispatch "production"	any	production	main	docs.userose.ai

Local Development¶

Prerequisites¶

Python 3.11+
Poetry (installed automatically by bootstrap)

Setup¶

cd docs

# Install dependencies (creates .venv and installs packages)
just install

# Or force reinstall
just install-force

Running Locally¶

# Start dev server with hot reload
just dev

The documentation will be available at http://localhost:8001.

Building¶

# Build static site to ./site directory
just build

Manual Deployment¶

You can manually deploy to either environment:

cd docs

# Deploy to test environment (docstest.userose.ai)
just deploy test

# Deploy to production (docs.userose.ai)
just deploy production

Automatic Deployment (CI/CD)¶

The GitHub workflow (.github/workflows/deploy-docs.yml) automatically deploys:

On push to develop: Deploys to test environment
On push to main: Deploys to production environment
Manual trigger: Choose environment from GitHub Actions UI

Workflow Triggers¶

The workflow runs when:

Files in docs/** are modified
The workflow file itself is modified
Manually triggered via workflow_dispatch

Project Structure¶

docs/
├── src/                    # Documentation source files
│   ├── index.md           # Home page
│   ├── architecture.md    # Architecture overview
│   ├── documentation.md   # This file
│   ├── features/          # Feature documentation
│   ├── backend/           # Backend documentation
│   └── frontend/          # Frontend documentation
├── public/                # Static assets
│   ├── _headers          # Cloudflare headers config
│   └── _redirects        # Cloudflare redirects config
├── mkdocs.yml            # MkDocs configuration
├── pyproject.toml        # Python dependencies
├── poetry.lock           # Locked dependencies
├── justfile              # Development commands
└── bootstrap.py          # Setup script

Writing Documentation¶

File Format¶

All documentation is written in Markdown with MkDocs extensions:

Admonitions for callouts (note, warning, tip, etc.)
Code blocks with syntax highlighting
Mermaid diagrams for flowcharts and sequences
Tables for structured data

Adding a New Page¶

Create a new .md file in the appropriate directory under src/
Add the page to the navigation in mkdocs.yml
Link to related pages where appropriate

Example: Adding a Feature Doc¶

# 1. Create the file
touch docs/src/features/my-new-feature.md

# 2. Edit mkdocs.yml to add to navigation

# In mkdocs.yml
nav:
  - Features:
      - Overview: features/index.md
      - My New Feature: features/my-new-feature.md  # Add this line

Markdown Extensions¶

Admonitions¶

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

!!! warning
    This is a warning without a custom title.

!!! tip "Pro Tip"
    This is a tip callout.

Title

This is a note callout.

Warning

This is a warning without a custom title.

Pro Tip

This is a tip callout.

Mermaid Diagrams¶

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

flowchart LR A[Start] --> B[Process] B --> C[End]

Code Blocks¶

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

def hello():
    print("Hello, World!")

Tables¶

| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

Column 1	Column 2
Value 1	Value 2

Cloudflare Configuration¶

Custom Domains¶

DNS configuration for custom domains:

Type	Name	Target
CNAME	docs	rose-docs.pages.dev
CNAME	docstest	test.rose-docs.pages.dev

Headers and Redirects¶

Custom headers and redirects are configured in public/_headers and public/_redirects, which are copied to the build output.

Troubleshooting¶

Build Fails¶

# Clean and rebuild
just clean
just install
just build

Missing Dependencies¶

# Force reinstall
just install-force

Port Already in Use¶

# Use a different port
.venv/bin/mkdocs serve -a localhost:8002

# Show all available commands
just --list

# Show DNS configuration
just show-dns

# Clean build artifacts
just clean