Contributing

Local Editing Workflow

How to preview and edit documentation locally with hot module reload before publishing.

When editing documentation of other projects, it may sometimes be convenient to have a means to preview how they will look in Ontopix DevDocs. This workflow solves precisely that need.

Overview

This workflow allows documentation editors to preview their changes locally with hot module reload (HMR) before publishing to production. You'll edit markdown files in your source repository and see changes instantly reflected in the docs portal running on your machine.

┌─────────────────────────────────────────────────────────────┐
│  Your Machine                                               │
│                                                             │
│  ┌──────────────────┐        ┌─────────────────────────┐    │
│  │ docs.dev (clone) │◄───────│ Source Repo (clone)     │    │
│  │ pnpm dev         │  HMR   │ engineering-handbook/   │    │
│  │ localhost:3000   │        │ *.md files              │    │
│  └──────────────────┘        └─────────────────────────┘    │
│                                       │                     │
└───────────────────────────────────────┼─────────────────────┘
                                        │
                                   git push
                                        │
                                        ▼
                              ┌────────────────────┐
                              │ GitHub             │
                              │ source repo        │
                              └────────┬───────────┘
                                       │
                                  webhook POST
                                       │
                                       ▼
                              ┌────────────────────┐
                              │ AWS Amplify        │
                              │ docs.ontopix.dev   │
                              └────────────────────┘

Prerequisites

Node.js 22+
pnpm package manager
Git
A GITHUB_TOKEN with read access to Ontopix repositories (if you want to see the remote collections pulled locally).
Both repositories cloned locally

Step-by-Step Setup

Step 1: Clone Both Repositories

Clone the documentation portal and the source repository you want to edit:

# Clone the docs portal
git clone https://github.com/ontopix/docs.dev.git
cd docs.dev

# Clone your source repository (in a separate directory)
cd ..
git clone https://github.com/ontopix/engineering-handbook.git
# or: git clone https://github.com/ontopix/schemas.git
# or: git clone https://github.com/ontopix/stylebook.git

Step 2: Configure the Docs Portal

Set up the docs.dev repository:

cd docs.dev

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env and add your GITHUB_TOKEN (if you want to see remote collections locally)

Step 3: Create Local Collection Configuration

Create your local preview configuration:

# Copy the example file
cp collections.local.example.ts collections.local.ts

Actually, pnpm install will create a copy of collections.local.example.ts into collections.local.ts because it is needed to run the app.

Edit collections.local.ts to point to your local repository:

import type { CollectionSpec } from './shared/collectionUtils'

export const localCollectionsSpec: Record<string, CollectionSpec> = {
  engineering: { // use the key of the real collection or any other key
    source: {
      cwd: '../engineering-handbook',
      include: '**/*.md', // Adjust pattern for your repo structure
      prefix: '/engineering' // For convention should be the same as the key, but not enforced
    },
    frontpage: '/engineering/readme',
    navigation: {
      title: 'Engineering Handbook',
      description: 'Preview of local engineering handbook',
      icon: 'i-lucide-wrench',
      badge: 'Local' // good to distinguish it in the UI
    }
  }
}

Avoid relative paths. Use the full path like /Users/yourname/projects/engineering-handbook. When using relative paths, changes made to the collection files are not being noticed by Nuxt Content, and the hot reload is therefore not happening.

If collections.local.ts contains at least one collection, then remote collections are not pulled from github. This is an intentional feature of the editorial mode to ease the process of editing documentation. With this behavior, you don't need GitHub tokens or the like to test your docs.

Step 4: Match Include Pattern to Repository Structure

The include pattern must match your repository's documentation structure:

Repository	Docs Location	Include Pattern
`engineering-handbook`	Root directory	`'*/.md'`
`schemas`	`doc/` subdirectory	`'doc/*/.md'`
`audit-utils`	`doc/` subdirectory	`'doc/*/.md'`
`stylebook`	`packages/content/`	`'packages/content/*/.md'`

If in doubt, replicate a collection from the collections.ts file.

Step 5: Start the Development Server

pnpm dev

The portal will start at http://localhost:3000 with:

Your local collection visible in navigation with a "Local" badge
Git-based collections (engineering, schemas, etc.) hidden to reduce build time
Bundled collections (docs, landing page) still visible for context

Understanding Collections in Production

The collections.ts file is the single source of truth for all collections in production:

// collections.ts (excerpt)
export const collectionsRegistry = {
  engineering: {
    source: {
      repository: 'https://github.com/ontopix/engineering-handbook',
      include: '**/*.md',
      prefix: '/engineering'
    },
    frontpage: '/engineering/readme',
    navigation: {
      title: 'Engineering Handbook',
      description: 'Engineering standards and practices',
      icon: 'i-lucide-wrench'
    }
  },
  // ... other collections
}

Key properties:

source.repository — GitHub repository URL (omitted for bundled collections)
source.include — Glob pattern matching documentation files
source.prefix — URL prefix for the collection (e.g., /engineering)
frontpage — Default landing page path
navigation — Display configuration (title, icon, badge, description)

Local Editing Workflow

1. Make Changes

Edit markdown files in your source repository:

cd ../engineering-handbook
vim patterns/infrastructure-layout.md
# Make your changes

2. See Changes Instantly

Switch to your browser at http://localhost:3000 — changes appear automatically via HMR (Hot Module Reload). No manual refresh needed.

You can edit markdown files and see changes within 1-2 seconds in the browser.

3. Review in Context

Navigate through the portal to:

Check your changes render correctly
Verify navigation and links work
Test MDC components and callouts
Ensure frontmatter is correct

4. Commit and Push to Source Repository

Once satisfied with your changes:

cd ../engineering-handbook

git add .
git commit -m "docs: update infrastructure layout pattern"
git push origin main

Commit to your source repository (e.g., engineering-handbook), not to docs.dev.

Publishing Changes to Production

After pushing to your source repository's main branch:

Automatic Rebuild (If CI/CD Configured)

If the source repository has the webhook workflow configured (see CI/CD Setup):

GitHub Action triggers automatically on push
Action POSTs to Amplify webhook
Amplify rebuilds docs.ontopix.dev
Your changes appear in production (~3-5 minutes)

You can monitor the rebuild at:

AWS Amplify Console → docs.dev app
GitHub Actions tab in your source repository

Manual Rebuild (If No CI/CD)

If the source repository doesn't have CI/CD configured:

# From the docs.dev repository
task infra:trigger-build

This manually triggers an Amplify rebuild that will fetch your latest changes.

Troubleshooting

Local collection doesn't appear

Verify collections.local.ts has been created (not just the .example file)
Check that cwd uses an absolute path
Ensure the include pattern matches your repo structure
Restart the dev server (Ctrl+C and pnpm dev again)

Changes don't hot-reload

Verify you're editing files in the correct repository
Check that file paths match the include pattern
Look for TypeScript errors in the terminal
Try manually refreshing the browser

"Cannot find module" errors

Run pnpm install in the docs.dev repository
Ensure Node.js version is 22+ (node --version)
Check that .env file exists with GITHUB_TOKEN

Local collection shows "404 Not Found"

Check frontpage path matches an actual file
For repos using README.md, use /local/readme (lowercase)
Verify prefix matches the URLs you're trying to access

Best Practices

Always use absolute paths — Avoid ~ or relative paths in collections.local.ts
Keep collections.local.ts private — This file is gitignored and should stay local to your machine
Test before publishing — Review all changes in local preview before pushing to production
Use semantic commit messages — Follow conventional commits (e.g., docs: add API reference)
Verify CI/CD is working — After pushing, check that the rebuild triggers automatically
Clean up local branches — Delete feature branches after merging to keep repositories tidy

Multiple Local Collections

You can preview multiple repositories simultaneously:

// collections.local.ts
export const localCollectionsSpec: Record<string, CollectionSpec> = {
  engineering: {
    source: {
      cwd: '/Users/yourname/projects/engineering-handbook',
      include: '**/*.md',
      prefix: '/engineering'
    },
    frontpage: '/engineering/readme',
    navigation: {
      title: 'Engineering (Local)',
      icon: 'i-lucide-wrench',
      badge: 'Local'
    }
  },
  schemas: {
    source: {
      cwd: '/Users/yourname/projects/schemas',
      include: 'doc/**/*.md',
      prefix: '/schemas'
    },
    frontpage: '/schemas/readme',
    navigation: {
      title: 'Schemas (Local)',
      icon: 'i-lucide-database',
      badge: 'Local'
    }
  }
}

Both collections will appear in navigation with "Local" badges.

What's Next?

Markdown Guide — Learn about MDC components and syntax
CI/CD Setup — Configure automatic rebuilds for your source repository
Collections Overview — Understand the full collection architecture

Contributing Content

How to add or update documentation in this portal.

CI/CD Setup for Source Repos

How to configure automatic documentation rebuilds when source repositories change.