DocHub
DocHub/DocHub/Content System/Authoring Guide
How to write and add documentation pages

Authoring Guide

Adding a New Page

  1. Create a .md file in the appropriate content/{project}/{subproject}/ directory
  2. Add YAML frontmatter with at least title and summary
  3. Write markdown content
  4. The page is immediately available in dev mode (no build step)

Adding a New Subproject

  1. Create the directory under content/{project}/
  2. Add _subproject.yaml with id, name, description, and schema_coverage
  3. Add at least one .md file
  4. The subproject appears in navigation and manifests automatically

Adding a New Project

  1. Create the directory under content/
  2. Add _project.yaml with id, name, and description
  3. Add at least one subproject with one page
  4. The project appears on the hub landing page and in the master manifest

Markdown Features

DocHub uses markdown-it with these capabilities:

  • Standard CommonMark markdown
  • Tables (GitHub-flavored)
  • Fenced code blocks with syntax highlighting (specify language after triple backticks)
  • Auto-linked URLs
  • Smart quotes and typographic replacements
  • Raw HTML passthrough
  • Heading anchor links (click heading to get permalink)

Supported Code Languages

Any language supported by highlight.js works in fenced code blocks:

```typescript
const x: number = 42;
```

```json
{ "key": "value" }
```

```bash
npm run build
```

```yaml
name: example
```

Cross-References

Use the references frontmatter field to declare dependencies between subprojects:

references:
  - target: dochub/api          # project/subproject format
    type: depends_on
  - target: dochub/deployment
    type: consumed_by

Reference types are freeform strings. The daily agent validates that referenced subprojects actually exist and flags broken references.

Page Ordering

Pages in the sidebar are sorted by the order frontmatter field (ascending), then alphabetically by slug. Use increments of 1 for normal ordering:

order: 1   # First page
order: 2   # Second page
order: 3   # Third page

Pages without an order field default to 999 and appear last.

Adding an Overview Page (Tier 1)

Overview pages are self-contained HTML files in content/_overviews/ with embedded CSS. To add one:

  1. Create content/_overviews/{id}.html — a complete HTML document with all styles inline
  2. Edit src/routes/overview.ts and add the page to the overviewPages array with id, title, subtitle, and icon
  3. Recompile TypeScript (npx tsc) since the route file changed
  4. The page is immediately available at /overview/{id}

Design Guidelines

Follow the existing overview style:

  • system-ui font, #1e293b text, #ffffff background
  • Blue accent (#2563eb) for section headers with left bar indicator
  • Numbered flow steps: blue circles with white numbers
  • Tables with uppercase gray headers
  • Color-coded badges (Critical=red, Important=yellow, Optional=blue)
  • Cards with subtle borders and 12px border-radius
  • Sections with #f8fafc background, padded, rounded
  • “Drill Down” links at the bottom linking to relevant Tier 2 docs
  • Navigation breadcrumb at the top linking back to /overview/

Dev Workflow

In development, content is rendered on-the-fly from the filesystem. There is no build step — save a .md file and reload the browser. The nav tree, manifests, and search all read directly from content/.

Overview HTML files are also served directly from the filesystem. Save the .html file and reload.

In production, the build-site.ts script can pre-render manifests and raw files to build/, but the HTML rendering still happens at request time.