Contact Us

Content Collections

DOC-00005 reference implementor, developer, editor

The content system is built on Astro’s content collections API. All content lives in src/content/ and is validated against Zod schemas defined in src/content.config.ts.

Who this is for

  • Implementors working with frontmatter schemas, content routing, or collection configuration
  • Developers adding new collections or modifying schema definitions
  • Editors understanding how content files map to published pages

Schema Locations

All content collections use Zod-validated frontmatter schemas. The authoritative field inventory is always the schema source file — this doc teaches the system model, not an exhaustive field list.

CollectionSchema locationOwnership
pages, articlessrc/content.config.ts (contentSchema)SITE-OWNED
theme-docsdefineDocsCollection() in src/core/config/theme-docs-collection.tsCORE-OWNED
site-docsdefineDocsCollection() in src/site/config/site-docs.tsSITE-OWNED
fragmentssrc/content.config.ts (inline)SITE-OWNED

Both docs collections use the shared defineDocsCollection() factory from src/core/config/docs-collection-factory.ts (CORE-OWNED). The factory produces a validated Astro collection from parameters — each collection customizes topics, docId prefix, and extensions.

Collections Overview

CollectionPurposeRouted?
pagesUtility and simple content pages (about, contact, legal)Yes
articlesBlog posts, news, case studiesYes
docsInternal documentation for implementors, developers, and AI agentsYes
fragmentsReusable content blocks composed into other pagesNo

Pages and Articles

Pages and articles share the same schema. The distinction is in URL routing and default behavior, not field structure.

Representative frontmatter

---
title: About Us
description: Learn more about our team and mission.
slug: /about
draft: false
category: company
tags:
  - team
  - mission
heroTitle: Meet the Team Behind the Work
---

Key fields

  • title (required) — page title, used as <h1> and in listings
  • description (required) — short summary for meta tags and listing cards
  • slug (optional) — overrides the default URL path derived from the file path and name
  • draft (default: false) — when true, excluded from builds, sitemap, and indexing
  • noindex (default: false) — suppresses search engine indexing for the page
  • datePublished / dateModified (optional, ISO 8601) — resolves in order: frontmatter value → git commit date → file date
  • category (optional) — primary category for taxonomy
  • tags (optional) — array of tag strings
  • heroTitle (optional) — marketing-oriented title override for hero sections
  • shortTitle (optional) — compact label for navigation and breadcrumbs
  • toc (default: true) — enables table of contents generation
  • readingTime (default: true) — enables estimated reading time display
  • lightbox (optional, boolean) — enables or disables the image lightbox for a specific page; when omitted, the collection default from src/site/config/platform.config.ts applies (REQ-00049)

Taxonomy

Categories

Categories use an explicit mapping table defined in site config (siteConfig.taxonomy.categories). Each entry maps a display name to a URL slug:

// src/site/config.ts
taxonomy: {
  categories: {
    "Company News": "company-news",
    "Case Studies": "case-studies",
    "Engineering":  "engineering",
  },
}

The frontmatter category value is matched case-insensitively against the display names in this table. Values that do not match any registered category generate a build-time warning. Category pages are indexable by default (siteConfig.taxonomy.categoryIndexable).

Tags

Tags are emergent — no registration is required. Any string in the tags array becomes a valid tag. Different casings (TypeScript, typescript, TYPESCRIPT) resolve to the same tag via slug normalization at build time.

Tag pages are noindex by default (siteConfig.taxonomy.tagIndexable).

Generated taxonomy pages

URL patternDescription
/articles/categories/Index of all categories
/articles/categories/{slug}/Articles in a specific category
/articles/categories/{slug}/page/{n}/Paginated category listing
/articles/tags/Index of all tags
/articles/tags/{slug}/Articles with a specific tag
/articles/tags/{slug}/page/{n}/Paginated tag listing

Heading authoring baseline

  • The page <h1> comes from frontmatter (title, or heroTitle where supported).
  • In markdown/MDX body content, start at ## and below.
  • Do not author prose # headings in routed collections (pages, articles, docs).
  • # remains valid inside fenced code blocks for examples/comments.

For the complete field inventory and validation rules, see src/content.config.ts.

Docs

The docs collection has additional fields for documentation-specific metadata. The full frontmatter contract is documented in the Documentation Guide (DOC-00001).

Representative frontmatter

---
title: Design Tokens
description: Reference for the three-layer design token architecture.
docId: DOC-00004
topic: design-system
audience:
  - implementor
  - developer
docType: reference
order: 4
datePublished: 2026-02-27
draft: false
relatedDocs:
  - DOC-00002
---

Key differences from pages/articles

  • docId (required) — immutable identifier in DOC-NNNNN format; used for cross-references
  • topic — groups related docs for sidebar navigation
  • audience — who the doc is written for (implementor, developer, editor)
  • docType — document classification (guide, reference, policy, how-to, tutorial)
  • noindex defaults to true — docs are internal reference, not marketing content
  • showRequirements (default: true) — renders a requirements section if any requirement references this docId
  • relatedDocs — enables a related documents section when populated

Docs default overrides

FieldDocs DefaultShared DefaultReason
noindextrue (theme-docs) / false (site-docs)falseTheme-docs are internal; site-docs are customer-facing
tocStartLevel21Docs start TOC at H2
tocEndLevel32Docs end TOC at H3

For the complete field inventory, see src/content.config.ts. For the full docs frontmatter contract and writing standards, see the Documentation Guide (DOC-00001).

Fragments

Fragments are not routed — they have no URL and are never rendered as standalone pages. They are reusable content blocks consumed programmatically by other pages. The collection uses a two-directory loader that merges entries from src/core/content/fragments/ (core layer) and src/content/fragments/ (site layer).

Representative frontmatter

---
title: Company Mission Statement
notes: Used on the about page and footer.
fragmentId: mission-statement
---
  • fragmentId (required) — stable reference key used by consuming pages
  • title (optional) — internal editorial label, not rendered as a heading
  • notes (optional) — editorial context for content authors

URL Routing

CollectionURL patternExample
pages/{slug}//about/, /contact/
articles/articles/{file-slug}//articles/case-study-acme/
docs/theme-docs/{file-slug}//theme-docs/design-tokens/
fragments(not routed)—
  • Trailing slash is enforced on all routes
  • All routed collections support an optional slug field that overrides the default path-derived URL
  • Canonical URLs are auto-generated from siteUrl + route; the canonical field overrides when set

Draft Content

When draft: true on any collection entry:

  • Excluded from production build output
  • Excluded from sitemap
  • Marked noindex, nofollow for robots
  • Visible on the dev server for preview

Noindex Defaults

CollectionDefaultRationale
pagesIndexedMarketing/utility pages should be discoverable
articlesIndexedBlog/news content should be discoverable
docsNot indexedInternal reference documentation

Media and Images

Image Optimization (REQ-00076)

All images used in content must go through Astro’s built-in image optimization pipeline. Use the <Image> component from astro:assets rather than raw <img> tags.

---
import { Image } from "astro:assets";
import heroImage from "@/assets/images/hero.jpg";
---

<Image src={heroImage} alt="Descriptive alt text" width={1200} height={630} />

Astro automatically generates optimized WebP/AVIF variants, adds width and height to prevent layout shift, and applies lazy loading by default.

For images referenced in content frontmatter, define the field as an image reference type in the collection schema so Astro can process it at build time.

Art Direction (REQ-00077)

When different crops or aspect ratios are needed across breakpoints, use the <Picture> component or a native <picture> element with <source media="..."> elements:

---
import { Picture } from "astro:assets";
import heroDesktop from "@/assets/images/hero-desktop.jpg";
---

<Picture
  src={heroDesktop}
  alt="Descriptive alt text"
  formats={["avif", "webp"]}
/>

For true art direction (different source images per viewport), use a native <picture> element pointing to separately optimized assets for each breakpoint.

Figures and Captions (REQ-00079)

Figures with captions must use semantic <figure> and <figcaption> markup:

<figure>
  <Image src={image} alt="Chart showing quarterly growth" />
  <figcaption>Q3 2025 revenue by region. Source: Finance team.</figcaption>
</figure>

Rules:

  • <figure> wraps the image and its caption as a unit.
  • <figcaption> is the only text child alongside the image — do not nest headings inside figures.
  • Alt text and figcaption are complementary: alt describes the image content; figcaption provides context, attribution, or explanation.
  • Decorative images (no informational content) use alt="" and may omit the figure wrapper.

REQ-00011 normative Hybrid rendering activation shall be explicit and deterministic (config or frontmatter driven), not inferred implicitly.
REQ-00059 normative Markdown and/or MDX authoring shall be supported.
REQ-00060 implemented Frontmatter validation shall be enforced.
REQ-00061 implemented Draft content states shall be supported.
REQ-00062 implemented Draft content shall be excluded from sitemap and indexing outputs.
REQ-00063 implemented Draft content shall imply noindex/nofollow directives.
REQ-00065 implemented Estimated reading time shall be supported.
REQ-00066 implemented Table of contents generation shall be supported.
REQ-00067 implemented Modified time shall be supported.
REQ-00068 implemented Modified time shall resolve from a deterministic source hierarchy.
REQ-00069 implemented Primary category taxonomy shall be supported.
REQ-00070 implemented Tags taxonomy shall be supported.
REQ-00071 implemented Category and tag listings shall support pagination by default.
REQ-00075 normative Content rendering failures shall degrade gracefully.
REQ-00076 normative Images shall be optimized automatically.
REQ-00077 normative Art-directed image support shall be provided.
REQ-00079 normative Figures and captions shall follow consistent semantic patterns.
REQ-00092 implemented Generated URLs shall be overridable.
REQ-00094 implemented Content shall be able to exclude itself from sitemap outputs.
REQ-00141 implemented Content entries in `pages`, `articles`, and `docs` collections shall require a non-empty `description` field.
REQ-00142 implemented Documentation routes shall use slug-based canonical URLs (for example, `/theme-docs/<slug>/`). Immutable `docId` values (format `DOC-00001`) shall remain required for internal cross-reference and traceability.
REQ-00144 implemented Fragment references used by routed content shall resolve to existing fragment IDs at build/validation time.
REQ-00169 implemented Static `.astro` pages and markdown content entries shall support an optional `heroTitle` field that, when present, overrides `title` as the rendered page H1 heading while `title` continues to drive the browser tab title and SEO `<title>` tag.
REQ-00170 implemented Static `.astro` pages and markdown content entries shall support an optional `shortTitle` field for use in condensed-space surfaces such as navigation labels, breadcrumbs, and card titles.
REQ-00179 implemented Category listing pages shall be indexable by default. Tag listing pages shall be configurable, defaulting to not indexed. Tag pages shall exist regardless of indexability and shall emit noindex directives rather than returning 404.
REQ-00182 normative Authors shall be shielded from direct Tailwind utility class usage where reasonable. Content authoring surfaces shall not require knowledge of the underlying styling framework.
REQ-00203 implemented The system shall support reusable markdown content fragments via a unified fragments collection that supersedes the original page-fragments collection, with core/site shadow support.
REQ-00207 normative Collection-driven routing shall be required for entries under `src/content/pages/`; this requirement does not prohibit additional public route families backed by the `articles` collection, `docs` collection, or static `.astro` pages.
REQ-00208 implemented The system shall provide the C5 section baseline set (`Hero`, `CallToAction`, `InfoCards`, `FeatureGrid`, `Testimonials`) as reusable section components composed from shared primitives.
REQ-00209 implemented Page, article-detail, and docs-detail routes shall render heading-band content in the `PageGridLayout` `subheader` slot using `Hero`; without actions or image, `Hero` renders as a compact page-title band.
REQ-00266 implemented Content collections shall support an optional linkedRoute frontmatter field that associates a metadata-only content entry with a static .astro page route, enabling programmatic discovery of static pages via getCollection() without requiring those pages to use file-based content routing.

Search

Search across pages and articles. Use arrow keys to navigate results.

Search across pages and articles.

Loading search...

Search is unavailable. Please try again later.

    No results for ""

    Try different keywords or fewer words.

    This site uses cookies and tracking technologies to improve your experience. You can accept all tracking, reject optional tracking, or allow only required functionality. Privacy Policy