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:

1. Files in docs/** are modified
2. The workflow file itself is modified
3. 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

1. Create a new .md file in the appropriate directory under src/
2. Add the page to the navigation in mkdocs.yml
3. 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

Maintaining the glossary

src/glossary.md is the shared vocabulary: a term means the same thing across code, schema, backoffice, and docs. Treat it as living reference, not a one-off.

• Add a term when a concept gets reused. The moment the same word starts appearing in an ADR, a schema column, and a backoffice label — or you catch yourself re-explaining it in a second place — define it once here and link to it instead of redefining. Do not pre-populate speculative terms.
• Keep each entry short and scope-stable: what it is, what owns it, and any invariant that is always true. Leave history, rollout, and per-feature detail in the ADR or topic page; link there.
• Update, don't fork. When a concept's meaning shifts, edit the existing entry so the two can never drift. Remove a term when it stops being used.
• Group by domain under an ## heading (e.g. Sites, knowledge, and routing), so sections can be extended independently as areas mature.

Add a class diagram when the relationships between terms matter more than the terms alone — ownership, cardinality, or which attribute lives on which entity. Model it as a UML class diagram, not a flowchart:

• Concepts that own each other are classes joined by composition (*--); annotate every edge with a multiplicity ("1", "0..*").
• Parameters are fields inside a class, never boxes of their own — an enabled flag or a status enum belongs in its entity, not beside it.
• Put constraints and derived relationships (e.g. "exactly one canonical root", "crawl seeds derive from roots") in a note, not in the boxes.
• Keep enum value lists (draft|live|disabled) in the prose definitions; Mermaid class bodies break on |, «», and similar characters.

Mermaid renders inline, so a glossary diagram needs no build step — but there is no local Mermaid linter, so hand-check syntax, or preview with just dev.

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

Related Commands

# Show all available commands
just --list

# Show DNS configuration
just show-dns

# Clean build artifacts
just clean