Contributing Content

How Documentation Gets Here

There are two ways content appears in this portal:

1. Local content — Markdown files in this repository's content/docs/ directory. This is where portal-level documentation lives (what you're reading now).
2. External collections — Markdown files pulled from other GitHub repositories (Engineering Handbook, Stylebook, etc.). These are configured in content.config.ts.

Adding Local Content

To add a page to the portal's own documentation:

1. Create a .md file in the appropriate directory under content/docs/
2. Add frontmatter with at least title and description
3. Write your content in Markdown (with optional MDC components)
4. Push to the repository

File Naming

Files and directories use numeric prefixes for ordering:

content/docs/
├── 1.about/
│   ├── 1.index.md      → /docs/about
│   └── 2.for-ai-agents.md → /docs/about/for-ai-agents
├── 2.contributing/
│   ├── 1.index.md      → /docs/contributing
│   └── 2.markdown.md   → /docs/contributing/markdown

The numeric prefix (1., 2.) controls sidebar order but is stripped from the URL.

Frontmatter

Every page needs frontmatter at the top:

---
title: Page Title
description: A brief description of this page.
navigation:
  icon: i-lucide-file-text  # optional sidebar icon
---

Navigation

Each directory can include a .navigation.yml file to set the section title and icon:

title: Section Name
icon: i-lucide-folder

Adding a New External Collection

To integrate documentation from another GitHub repository:

1. Add a new collection in content.config.ts:

myCollection: defineCollection({
  type: 'page',
  source: {
    repository: {
      url: 'https://github.com/ontopix/my-repo',
      auth: {
        username: 'ontopix',
        token: process.env.GITHUB_TOKEN,
      },
    },
    include: '**/*.md',
    prefix: '/my-collection',
  },
  schema: defaultContentSchema,
})

2. The collection will automatically appear in navigation after the next build.

Collection Index Page Requirements

Each external collection must have a README.md file at its root with proper frontmatter. This file becomes the collection's index page (e.g., /engineering, /stylebook).

Required frontmatter for collection README.md:

---
title: Collection Name
description: Brief description of this collection.
navigation:
  icon: i-lucide-book  # optional sidebar icon
---

Source Repository Structure

External repositories should follow this structure:

my-repo/
├── README.md              # Collection index (required)
├── 1.getting-started/
│   ├── README.md          # Section index
│   └── installation.md
├── 2.guides/
│   ├── README.md
│   └── ...
└── .navigation.yml        # Optional: collection-level navigation config

Key conventions:

• Use README.md for directory index pages (GitHub convention)
• Use numeric prefixes (1., 2.) for ordering
• Every page needs title and description frontmatter