New Doc Page

Then add TOC entries in the tocByPage record. Always include an "Overview" entry first, then add section entries based on the content plan:

"<page-slug>": [
  { title: "Overview", id: "overview" },
  { title: "Section Name", id: "section-id" },
],

Step 3: Register in components/docs/page-content.tsx

Add the import at the top with the other page imports:

import { PageNamePage } from "@/components/docs/pages/<page-slug>"

Add the entry in the pageComponents record (maintain alphabetical order by slug):

"<page-slug>": PageNamePage,

Naming conventions:

• File name: <page-slug>.tsx (exception: if the slug conflicts with a reserved name like "settings", use <slug>-page.tsx)
• Export name: PascalCase of slug + "Page" (e.g., ci-steps → CiStepsPage)

Step 4: Create the page component

Create the file at components/docs/pages/<page-slug>.tsx following this exact structure:

import { Separator } from "@/components/ui/separator"
import { CodeBlock } from "@/components/docs/code-block"
import { Callout } from "@/components/docs/callout"
import { Badge } from "@/components/ui/badge"
import { Clock } from "lucide-react"

interface PageNamePageProps {
  onNavigate?: (section: string, item: string) => void
}

export function PageNamePage({ onNavigate }: PageNamePageProps) {
  return (
    <div className="space-y-0">
      {/* Header */}
      <header id="overview" className="mt-6 scroll-mt-20">
        <div className="flex items-center gap-3">
          <Badge variant="secondary" className="text-xs">
            Section Category
          </Badge>
          <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
            <Clock className="h-3 w-3" />
            <span>Last updated Mar 2026</span>
          </div>
        </div>
        <h1 className="mt-3 text-balance text-3xl font-bold tracking-tight text-foreground lg:text-4xl">
          Page Title
        </h1>
        <p className="mt-3 max-w-2xl text-pretty text-base leading-relaxed text-muted-foreground lg:text-lg">
          Description paragraph explaining what this page covers.
        </p>
      </header>

      <Separator className="my-8" />

      {/* Each section MUST have id + scroll-mt-20 for TOC linking */}
      <section id="section-id" className="scroll-mt-20">
        <h2 className="text-xl font-semibold text-foreground">Section Title</h2>
        <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
          Section content.
        </p>
      </section>

      <Separator className="my-8" />
    </div>
  )
}

Component usage rules

CodeBlock — for YAML/code examples:

<CodeBlock code={`code here`} language="yaml" filename="pipeline.yaml" showLineNumbers={true} highlightLines={[2, 5]} />

Callout — for info/warning/tip/success boxes:

<Callout type="info" title="Title" className="mt-4">Content here.</Callout>

Tables — wrap in overflow container:

<div className="mt-4 overflow-x-auto">
  <table className="w-full text-sm">
    <thead>
      <tr className="border-b border-border">
        <th className="px-3 py-2 text-left font-semibold text-foreground">Header</th>
      </tr>
    </thead>
    <tbody className="text-muted-foreground">
      <tr className="border-b border-border">
        <td className="px-3 py-2 font-medium text-foreground">Label</td>
        <td className="px-3 py-2">Value</td>
      </tr>
    </tbody>
  </table>
</div>

Bullet lists:

<ul className="mt-2 space-y-1.5 text-sm text-muted-foreground">
  <li className="flex items-start gap-2">
    <span className="mt-1.5 h-1.5 w-1.5 shrink-0 rounded-full bg-primary" />
    Item text
  </li>
</ul>

Inline code:

<code className="rounded bg-muted px-1.5 py-0.5 text-xs font-mono text-foreground">code</code>

Cross-page links — use the onNavigate prop:

<span className="cursor-pointer text-primary hover:underline" onClick={() => onNavigate?.("section-slug", "page-slug")}>
  Link text
</span>

External links:

<a href="https://..." target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1 text-primary hover:underline">
  Link text <ExternalLink className="h-3 w-3" />
</a>

YAML convention

All Harness pipeline YAML examples MUST use the v1 schema:

• No projectIdentifier, orgIdentifier, or identifier fields
• Flat stage types: type: deploy or type: ci
• Steps use with: (not spec:)
• Expression syntax: ${{ expression }} with snake_case

Step 5: Create markdown backup

Create a markdown backup file at docs/<section-slug>/<page-slug>.md.

The section-slug to directory mapping:

• getting-started → docs/getting-started/
• pipeline-spec → docs/pipeline-spec/
• connectors → docs/connectors/
• secrets → docs/secrets/
• platform → docs/platform/
• harness-code → docs/harness-code/
• step-library → docs/step-library/
• agents → docs/agents/
• dashboards → docs/dashboards/
• roadmap → docs/roadmap/

The markdown file must contain:

---