Docs Kit

The Docs Kit is a shared documentation system that lets child sites ship a working /site-docs/ section out of the box. It extracts the universal layers of the theme-docs system — schema validation, sidebar navigation, search filtering, and related-docs resolution — into reusable primitives that any documentation collection can consume.

Who this is for

• Implementors setting up a child site that needs its own documentation section
• Developers extending or customizing the seed collection
• AI agents working on documentation collection configuration

What the kit provides

The Docs Kit has three shared layers, all CORE-OWNED:

Layer 1 — Schema factory. defineDocsCollection() in src/core/config/docs-collection-factory.ts produces a validated Astro content collection from configuration parameters. It encapsulates the base schema (identity, metadata, display, TOC, SEO, relations, layout fields), extension mechanisms (additional docTypes, audience, custom Zod fields), and docId validation.

Layer 2 — Navigation component. DocsSidebarNav in src/core/components/docs/DocsSidebarNav.astro renders a topic-based accordion sidebar for any docs collection. It handles collection querying, topic grouping, ordering, accordion state, active-page marking, and cross-topic entries.

Layer 3 — Utility helpers. resolveRelatedDocs() in src/lib/resolve-related-docs.ts resolves relatedDocs docId references into { label, href }[] for any docs collection. Pagefind integration uses the convention that each collection’s filter value matches its collection name.

Theme-docs consumes these same layers with governance-specific extensions. ThemeDocsSidebarNav wraps DocsSidebarNav and adds the requirements link, showcases accordion, and linkedRoute URL override.

Seed collection anatomy

The seed ships 4 SITE-OWNED files plus content:

File	Purpose
src/site/config/site-docs.ts	Collection config: topic tuple, topic ordering, display config, factory call
src/pages/site-docs/index.astro	Index route with topic/type filtering, Pagefind search, pagination
src/pages/site-docs/[...slug].astro	Detail route with sidebar, TOC, breadcrumbs, prev/next, related docs
src/content/site-docs/**/*.md	Placeholder content entries (one per seed topic, plus topic-index entries)

The collection is also registered in src/content.config.ts (SITE-OWNED).

Configuration file

src/site/config/site-docs.ts exports:

• SITE_DOC_TOPICS — canonical topic list as a readonly tuple
• siteDocsTopicConfig — topic ordering with labels (type DocsTopicConfig)
• siteDocsRootLabel — breadcrumb root label
• siteDocsPerPage — pagination page size
• siteDocs — the collection definition (factory call result)

Route stubs

The index and detail routes are full-featured but SITE-OWNED — child sites can modify them freely. They use DocsSidebarNav directly (not ThemeDocsSidebarNav) and have no governance-specific logic.

Customization

Topics

Edit SITE_DOC_TOPICS and siteDocsTopicConfig in src/site/config/site-docs.ts. The topic tuple defines valid values enforced by the schema at build time. The topic config controls sidebar ordering and display labels.

docId prefix

Change the docIdPrefix parameter in the factory call. The prefix is used in the regex pattern that validates docId format. Default: "SDOC-" (pattern: SDOC-XXXXX).

Additional docTypes

Pass additionalDocTypes to the factory call to extend the base enum. The base types are: guide, reference, policy, how-to, tutorial, overview, topic-index.

export const siteDocs = defineDocsCollection({
  // ...
  additionalDocTypes: ["faq", "changelog"] as const,
});

Schema extensions

Use the extend parameter to add custom Zod fields to the frontmatter schema:

import { z } from "astro/zod";

export const siteDocs = defineDocsCollection({
  // ...
  extend: {
    product: z.string().optional(),
    version: z.string().optional(),
  },
});

Audience field

Pass audience to add a required audience enum array field:

export const siteDocs = defineDocsCollection({
  // ...
  audience: ["user", "admin", "developer"] as const,
});

When omitted (the seed default), the audience field defaults to an optional empty array.

noindex default

The factory’s noindexDefault parameter controls the default value of the noindex frontmatter field. Site-docs uses false (customer-facing, should be indexed). Theme-docs uses true (internal, should not be indexed).

Renaming the collection

To rename site-docs to something else (e.g., help-center):

1. Rename the content directory: src/content/site-docs/ → src/content/help-center/
2. Update contentGlob in the factory call
3. Update docIdPrefix if desired
4. Update the collection key in src/content.config.ts
5. Rename the route directory: src/pages/site-docs/ → src/pages/help-center/
6. Update all basePath, collection, and URL references in both route files
7. Update the Pagefind filter value to match the new collection name

Creating additional collections

To create a second docs collection alongside site-docs:

1. Create a new config file (e.g., src/site/config/kb-docs.ts) with its own topic tuple, topic config, and factory call
2. Register the collection in src/content.config.ts
3. Create route stubs in src/pages/kb-docs/ (copy and adapt the site-docs routes)
4. Create the content directory src/content/kb-docs/
5. Use a unique docIdPrefix (e.g., "KB-") to avoid docId collisions

Removing the system

To disable site-docs entirely:

1. Delete src/pages/site-docs/ (removes routes)
2. Delete src/content/site-docs/ (removes content)
3. Remove the "site-docs": siteDocs entry from src/content.config.ts
4. Optionally delete src/site/config/site-docs.ts

No feature flag is needed — Astro’s file-based routing means deleting the route files is sufficient.

Component and helper API reference

defineDocsCollection(options)

File: src/core/config/docs-collection-factory.ts

Parameter	Type	Required	Description
contentGlob	string	Yes	Content directory path (e.g., "./src/content/site-docs")
topics	readonly [string, ...string[]]	Yes	Canonical topic list (at least one)
docIdPrefix	string	Yes	Prefix for docId validation (e.g., "SDOC-")
noindexDefault	boolean	No	Default noindex value. Default: false
additionalDocTypes	readonly [string, ...string[]]	No	Extra docType values merged into base enum
audience	readonly [string, ...string[]]	No	Adds required audience enum array field
extend	Record<string, ZodTypeAny>	No	Additional Zod fields merged into schema

Returns an Astro collection definition (result of defineCollection()).

DocsSidebarNav props

File: src/core/components/docs/DocsSidebarNav.astro

Prop	Type	Required	Description
collection	string	Yes	Collection name (e.g., "site-docs")
basePath	string	Yes	Base URL path (e.g., "/site-docs")
topicConfig	DocsTopicConfig	Yes	Topic ordering and labels
activeTopic	string	No	Topic key to auto-expand
activeHref	string	No	Current page href for aria-current="page"
getEntryUrl	(entry) => string | undefined	No	Per-entry URL override
navLabel	string	No	Accessible landmark label. Default: "Documentation"

resolveRelatedDocs(collectionName, basePath, collectionSlug)

File: src/lib/resolve-related-docs.ts

Parameter	Type	Description
collectionName	string	Collection to query (e.g., "site-docs")
basePath	string	Base URL for generating hrefs (e.g., "/site-docs")
collectionSlug	string	Entry slug (from entry.id)

Returns Promise<{ label: string; href: string }[]>.