Content & Rendering Pipeline

Content Directory Structure

Files are the source of truth. No database needed — the file system IS the content model.

content/
  _master/ ← Root landing page (no sidebar)
    index.md
  _overviews/ ← Tier 1 visual HTML pages
    architecture.html
    content-pipeline.html
  {project}/ ← e.g. "dochub"
    _project.yaml ← id, name, description
    {subproject}/ ← e.g. "architecture"
      _subproject.yaml ← id, name, schema_coverage
      {page}.md ← Individual document
      index.md ← Optional: overrides auto listing

File	Purpose	Required
_project.yaml	Declares a project — without it, the directory is invisible to discovery	Required
_subproject.yaml	Declares a subproject with schema coverage tracking	Required
index.md	Custom landing page for a directory (replaces auto-generated card listing)	Optional
{page}.md	Individual documentation page with YAML frontmatter	Content

Tier 2 Rendering Pipeline

Every markdown page goes through this pipeline to become a full HTML page.

1

File Discovery — MarkdownService walks content/ directory, skipping files/dirs starting with _ or .

↓

2

Frontmatter Parsing — gray-matter extracts YAML header: title, summary, order, references

↓

3

Markdown Rendering — markdown-it converts body to HTML. Headings get anchor IDs via markdown-it-anchor

↓

4

Code Highlighting — highlight.js applies syntax colors to fenced code blocks (auto-detected language)

↓

5

TOC Extraction — H2/H3 headings are collected into a table of contents array

↓

6

Nav Tree Generation — Full sidebar navigation built from file system structure (projects → subprojects → pages)

↓

7

Template Assembly — TemplateService wraps content in 3-column layout: sidebar (left) + content (center) + TOC (right)

Tier 3 Manifest Pipeline

How the same content becomes machine-readable for Claude CLI and automated tools.

Source

_project.yaml

+ _subproject.yaml

→

Service

ManifestService

Scans all dirs

→

Output

JSON Manifests

3 levels deep

→

Consumer

Claude CLI

curl /api/manifest

Endpoint	Returns	Use Case
GET /api/manifest	All projects with subproject counts	Discover what documentation exists
GET /api/manifest/:project	Subprojects with schema coverage	Explore a project's sections
GET /api/manifest/:project/:sub	Documents with raw URLs + references	Find specific docs to read
GET /api/raw/:project/:sub/:page	Raw markdown source	Feed to AI for context
GET /api/search?q=term	Matching documents with excerpts	Find docs by keyword

Schema Coverage Model

Each subproject is tracked against 8 documentation sections. The daily agent reports coverage gaps.

Purpose

What & why

Architecture

Components

Variables

Env & config

API Endpoints

Routes

Handshakes

Communication

Data Model

Schema

Dependencies

What it needs

Status

Current state

Coverage is declared in _subproject.yaml and validated by the daily agent. A subproject at 100% has all 8 sections documented.

Markdown Frontmatter

Every .md file starts with YAML frontmatter that controls rendering and discovery.

Required Fields

title — Page heading and sidebar label

summary — Short description for cards and manifests

Optional Fields

order — Sort position (default 999)

references — Cross-links to other subprojects