Editing documentation

AlignTrue uses a docs-first architecture where the documentation site is the canonical source and repo root files are generated from it.

Architecture overview

apps/docs/content/ (canonical source - edit here)
  ↓
scripts/generate-repo-files.ts (transformation)
  ↓
README.md, CONTRIBUTING.md, DEVELOPMENT.md, POLICY.md (generated - don't edit)

This mirrors AlignTrue’s own philosophy: docs are the IR (Intermediate Representation), and repo files are exports.

File mapping

Editing workflow

1. Edit docs content

Edit files in apps/docs/content/:

# Edit the docs homepage (becomes README.md)
apps/docs/content/index.mdx
 
# Edit contribution guide (becomes CONTRIBUTING.md)
apps/docs/content/contributing/creating-packs.md
 
# Edit development pages (become DEVELOPMENT.md)
apps/docs/content/development/setup.md
apps/docs/content/development/workspace.md
apps/docs/content/development/commands.md
apps/docs/content/development/architecture.md
 
# Edit policy (becomes POLICY.md)
apps/docs/content/06-policies/index.md

2. Generate repo files

After editing, regenerate the repo root files:

pnpm generate:repo-files

This script:

• Reads docs content files
• Strips MDX frontmatter
• Transforms relative links to absolute URLs
• Adds auto-generation header and footer
• Writes to repo root

3. Verify changes

Check that generated files look correct:

git diff README.md CONTRIBUTING.md DEVELOPMENT.md POLICY.md

4. Commit both

Commit both the docs source and generated files:

git add apps/docs/content/ README.md CONTRIBUTING.md DEVELOPMENT.md POLICY.md
git commit -m "docs: Update documentation"

Link handling

Internal links (standard format)

Always use absolute paths from /docs/ root for internal documentation links.

<!-- ✅ Correct: Absolute path from /docs/ root -->
 
[Team Mode](/docs/03-concepts/team-mode)
[Quickstart Guide](/docs/00-getting-started/00-quickstart)
[CLI Reference](/docs/04-reference/cli-reference)
 
<!-- ❌ Incorrect: Relative paths -->
 
[Team Mode](./team-mode)
[Team Mode](../concepts/team-mode)

Why absolute paths?

• Robust during directory refactors
• Work consistently in all contexts (navigation, search, external links)
• Easier for contributors (one pattern to remember)
• Future-proof for multi-site deployments

Path format:

/docs/{section-number}-{section-name}/{page-name}

Examples:

• /docs/00-getting-started/00-quickstart
• /docs/01-guides/05-team-guide
• /docs/02-customization/overlays
• /docs/03-concepts/team-mode
• /docs/04-reference/cli-reference

How to find the correct path:

1. Check the _meta.json file in that section for the section number
2. Use the file name without the .md extension
3. Join with /docs/ prefix

The generation script automatically transforms these to absolute URLs for GitHub:

See [team mode](/docs/03-concepts/team-mode) for details.

External links

External links remain unchanged:

[GitHub repository](https://github.com/AlignTrue/aligntrue)

Anchor links

Anchor links are preserved:

See [installation](#installation) below.

Adding diagrams

AlignTrue documentation uses Mermaid for diagrams. Diagrams render as static content at build time with AlignTrue brand theming.

Mermaid syntax

Use standard Mermaid code blocks in your markdown:

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

Diagram types

Mermaid supports multiple diagram types:

Flowcharts:

```mermaid
graph TD
    Start[Need help?] --> Q1{Question type?}
    Q1 -->|Bug| Bug[File issue]
    Q1 -->|Feature| Feature[Discussion]
```

Sequence diagrams:

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Agent
 
    User->>CLI: aligntrue sync
    CLI->>Agent: Export rules
    Agent->>User: ✓ Complete
```

Architecture diagrams:

```mermaid
graph TD
    subgraph Solo Mode
        S1[AGENTS.md] --> S2[IR]
        S2 --> S3[Exports]
    end
```

AlignTrue branding

Diagrams automatically use AlignTrue brand colors:

• Primary nodes: Orange (#F5A623) with white text
• Secondary nodes: Light gray with dark borders
• Theme-aware: Adapts to light/dark mode

To highlight key nodes with brand colors:

```mermaid
graph LR
    A[Input] --> B[Process]
 
    style B fill:#F5A623,stroke:#F5A623,color:#fff,stroke-width:2px
```

Best practices

1. Keep diagrams simple - Focus on key concepts, avoid clutter
2. Use consistent terminology - Match docs language (IR, agents, sync)
3. Add context - Include brief explanation before/after diagram
4. Test rendering - Verify in both light and dark modes
5. Mobile-friendly - Ensure diagrams are readable on small screens

Examples in docs

See these pages for diagram examples:

• How it works - Homepage flow diagram
• Sync behavior - Sequence diagrams
• Workflows - Decision tree
• Solo vs team - Architecture comparison
• Customization - Decision flowchart

Testing locally

Test docs site

cd apps/docs
pnpm dev
# Open http://localhost:3001

Test generation script

pnpm generate:repo-files

Test both

pnpm docs:build

This runs generation then builds the docs site.

CI validation

CI enforces the docs-first workflow by validating that repo files match their generated versions.

Validation script

The validation script (scripts/validate-repo-files.ts) will be added in Phase 3 to:

• Run generation in dry-run mode
• Compare generated output with committed files
• Fail if differences detected (manual edits found)

What happens if you edit repo files directly

If you manually edit README.md, CONTRIBUTING.md, DEVELOPMENT.md, or POLICY.md:

1. Local workflow works fine
2. CI fails with validation error
3. Error message points to this docs editing guide
4. You need to:
   • Revert the manual edits
   • Make changes in apps/docs/content/ instead
   • Run pnpm generate:repo-files
   • Commit both docs source and generated files

Auto-generation headers

Generated files include a header warning against manual edits:

<!-- AUTO-GENERATED from apps/docs/content - DO NOT EDIT DIRECTLY -->
<!-- Edit the source files in apps/docs/content and run 'pnpm generate:repo-files' -->

And a footer linking back to the docs site:

---
 
**This file is auto-generated from the AlignTrue documentation site.**
**To propose changes, edit the source files in `apps/docs/content/` and run `pnpm generate:repo-files`.**

Benefits of docs-first

1. Single source of truth - Docs site is canonical
2. No drift - Repo files always match docs
3. Better structure - Multi-page docs vs single flat files
4. Easier maintenance - Edit in one place, export everywhere
5. Aligned with philosophy - IR-first → exports (just like AlignTrue itself)

Common tasks

Add a new docs page

1. Create file in apps/docs/content/
2. Update _meta.json in that directory
3. Add cross-links from related pages
4. Run pnpm generate:repo-files if it affects repo files

Reorganize docs structure

1. Move/rename files in apps/docs/content/
2. Update all _meta.json files
3. Update cross-references
4. Run pnpm generate:repo-files
5. Test navigation on docs site

Update README content

1. Edit apps/docs/content/index.mdx
2. Run pnpm generate:repo-files
3. Verify README.md looks correct
4. Commit both files

Questions?

• See getting started for development setup
• See workspace structure for repo layout
• See architecture for design principles