Skip to main content
For technical teams authoring against the per-tenant repo, two practical workflows are useful: a local preview that renders the atlas the same way the portal does, and continuous integration that validates content on every commit. This page covers both.
Local previews and CI are advanced features. Most brand owners do not need them. They are for studios authoring at scale and for engineering-led brand teams.

​
Local preview

The Brand Atlas CLI (brand-atlas on npm) renders an atlas locally: 
npm install -g brand-atlas-cli
brand-atlas preview ./
Running preview in an atlas repo:
  • Starts a local web server on http://localhost:3030.
  • Renders the atlas as the portal would render it.
  • Watches for file changes and re-renders.
The local preview is useful for:
  • Authoring a Horizon. Edit the MDX, see the result without uploading.
  • Iterating on style. Watch how voice rules read in the rendered form.
  • Cross-checking links. Internal links resolve the same way as in production.
The local preview does not have the full portal feature set; specifically:
  • No Henry or Oswald (the AI assistants require the live portal).
  • No Update Requests (they are a live-only workflow).
  • No Guest Passes (live-only).
What the preview does is the static content rendering. For everything else, push to the live atlas.

​
Validating content locally

The CLI includes a validator: 
brand-atlas validate ./
The validator runs the same checks the portal runs on upload:
  • MDX parses.
  • Frontmatter is complete and well-formed.
  • Components are in the supported set.
  • Assets exist.
  • Internal links resolve.
  • Voice rules pass.
Run before committing to catch issues before they reach the portal. The validator is also the right command to run in CI.

​
A CI workflow with GitHub Actions

A starter .github/workflows/validate.yml: 
name: Validate brand atlas

on:
  push:
    branches: [main]
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g brand-atlas-cli
      - run: brand-atlas validate ./
      - run: brand-atlas check-links ./
Two checks:
  1. validate. The full validator described above.
  2. check-links. Specifically catches internal-link breakage. Useful as a separate job because link breakage is a different kind of problem.
A pull request that fails validation should not be merged. The CI enforces this.

​
A pre-commit hook

For local enforcement, a pre-commit hook ensures the validator runs before any commit: 
# .git/hooks/pre-commit
#!/bin/bash
brand-atlas validate ./ || exit 1
Make it executable: chmod +x .git/hooks/pre-commit. The hook is per-developer (not shared via the repo by default). For team-wide hook management, use husky or similar.

​
Multi-atlas CI

For agencies running multiple atlases, a single CI workflow can validate all of them in parallel: 
jobs:
  validate:
    strategy:
      matrix:
        atlas:
          - acme
          - widget-co
          - studio-x
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          repository: studio/atlas-${{ matrix.atlas }}
          token: ${{ secrets.BRAND_ATLAS_TOKEN }}
      - run: npm install -g brand-atlas-cli
      - run: brand-atlas validate ./
A failure in any atlas blocks the merge. Useful for shared workflows that affect multiple clients.

​
Linting beyond validation

The validator catches structural problems. Two further linters are useful:
  1. markdownlint. Catches Markdown-shape issues (heading hierarchy, list consistency).
  2. A voice linter. Brand Atlas’s voice-rules.json can be consumed by an MDX-aware linter to surface banned vocabulary, suggest owned vocabulary, and flag voice-rule violations. The CLI ships a sample configuration.
Voice linting is most useful in CI for atlases with mature voice rules. For atlases still building their voice, the human read is more useful than a linter.

​
Performance budgets

For atlases with large image or asset libraries, the CLI includes a performance budget check: 
brand-atlas check-perf ./
Reports:
  • Total size of the atlas.
  • Largest individual assets.
  • Pages where rendered content exceeds a threshold (default 500KB).
Useful for keeping the atlas snappy as it grows. The thresholds are configurable.

​
Deploying through CI

For repo-direct workflows, every push to main is the deploy. The portal picks up the change within seconds. No separate deploy step is needed. For staged deployments (a preview branch for major changes), use a feature branch in the repo and switch the atlas’s branch in Settings → Advanced → Active branch. Switching back to main rolls the staged changes into production.

The GitHub-repo content model

The repo model.

Authoring in MDX

The format reference.

Managing multiple atlases

Multi-atlas patterns.