Documentation

This page documents the CSA Content Standards site itself—what it contains, how it is structured, how to read it, how to edit it, and how it is built and hosted.

⬇ Download this page

What This Site Is

CSA Content Standards is the authoritative reference for the Content Scaling Agent (CSA) and the editorial teams who work alongside it. It documents the rules, formats, and guidelines that govern how content is created, structured, optimized, and published across all CSA-affiliated outlets and destinations.

The site is versioned, machine-readable, and human-readable. Every rule has a section number. Every change is logged. The intent is that both a human editor and an AI agent can open any page and get a complete, unambiguous answer.

Site URL: csa-content-standards.pierce.tools Repository: github.com/piercewilliams/csa-content-standards JSON API: /api/reference.json

Content Sections

The site is organized into eleven numbered sections plus supporting reference pages.

Article Formats

Twelve article formats are documented under §3—3 active, 8 pending, 1 retired. Each has its own standalone page. Pending formats have spec pages but the spec is not yet finalized; retired formats are preserved for historical reference + conflict-register coverage but must not be selected for new content.

Section anchors (§3.1, §3.2, …) reflect introduction order and are stable URL targets; the visual list ordering below groups active first, then pending, then retired.

How to Read a Format Page

Scope: The conventions below apply to §3 Article Format pages and §4 Persona pages. §1, §2, §5, §6, §7, §8, and §9 are reference, policy, or workflow pages and do not use the red-text override system, pre-publish checklists, or “What to Avoid” tables.

All format pages share the same structure and conventions.

Red text

Text rendered in red marks guidance that overrides or extends General Guidelines. If a rule appears in red on a format page, it takes precedence over the General Guidelines equivalent for that format. If a rule is not in red, it inherits from General Guidelines.

Every format page opens with a blockquote summarizing exactly which General Guidelines rules are overridden and how.

Agent Routing

CSA rules are consumed by specialized inputs and human-only workflows—different rules go to different places. The site uses a two-layer routing system to make this machine-readable without changing the human-readable structure.

Layer 1—Page-level frontmatter

Every page declares which audiences it is relevant to via an agent_audiences field in its YAML frontmatter:

agent_audiences: [general-style, headline, seo, human-only]

This lets agents and tooling quickly determine whether a page is relevant to them at all, without parsing content.

Layer 2—Section-level HTML comments

Within pages that contain rules for multiple audiences, each subsection is prefixed with:

<!-- AGENT-AUDIENCE: general-style -->
<!-- AGENT-AUDIENCE: headline -->
<!-- AGENT-AUDIENCE: seo -->
<!-- AGENT-AUDIENCE: human-only -->

These comments are invisible on the rendered site but present in the raw Markdown source. To extract rules for a specific input, grep the raw Markdown for AGENT-AUDIENCE: [tag] and take everything between that comment and the next one.

The four tags

Canonical vocabulary

The tag definitions, coverage descriptions, and standard section-to-tag mapping for format pages are maintained in _data/agent_routing.yml. This is the single source of truth for the routing vocabulary—update it when tags are added or modified.

For new pages

When adding a new format page, follow the standard mapping documented in _data/agent_routing.yml under format_page_mapping. Add the agent_audiences frontmatter field and <!-- AGENT-AUDIENCE: --> comments to every section. The General Guidelines page shows the routing table and a worked example of how comments appear alongside content.

Also create a corresponding file in _includes/headline-formulas/[match].html—this is the format’s accordion block in the Headlines page Format-Specific Headline Formulas section. The Headlines page generates that list automatically from _data/navigation.yml in sidebar order, so the accordion will appear in the correct position as soon as navigation.yml is updated. The match value in navigation.yml must exactly match the include filename.

(REQUIRED) labels

Every spec element marked (REQUIRED) must be present before the article is published. Elements without this label are guidance, not requirements.

Pre-Publish Checklist

Every format page ends with a pre-publish checklist—a complete list of everything that must be verified before hitting publish. This checklist is format-specific and incorporates both the format’s own requirements and the relevant universal General Guidelines rules.

What to Avoid

Most format pages include a “What to Avoid” table listing prohibited patterns with the reason each is prohibited. The reason field is always one of: format requirement, tone requirement, or a General Guidelines rule reference.

Download button

The ⬇ Download this section button at the top of each page serves the raw Markdown source from this site (frontmatter and download-button stripped) at /assets/sources/<page>.md—useful for ingesting pages into external tools or agents. The same .md is the seed-file shape consumed by the McClatchy CSA backend at backend/style_guides/sources/.

How to Navigate the Site

Sidebar

The left sidebar is the primary navigation. Article Format pages are nested under the “Article Formats” group—click the group to expand it. All other sections are top-level links.

Search

A search box appears at the top of the sidebar on every page. Type a term and press Enter to go to the search page—results are drawn from the content of all docs pages. The search page also updates results live as you type.

Master Reference

The Master Reference is a single-document version of the entire site—all sections condensed into one page in order, with machine-readable section delimiters. It is the primary source for AI agents that ingest the standards as a single document.

Download the raw Markdown: /assets/sources/master-reference.md

JSON API

The JSON API provides a structured index of all sections and formats—section numbers, IDs, titles, statuses, and URLs. Use it to programmatically check which sections are active, which are pending, and where each section lives.

How to Edit the Site

All content is Markdown files in the /docs directory of the GitHub repository. Files can be edited directly in GitHub (pencil icon on any file → edit → commit) or cloned locally and pushed. Cloudflare Pages auto-deploys on every push to main; GitHub Pages is disabled (has_pages: false) since the 2026-04-23 migration.

Technical files (navigation, layout, CSS, search) live outside /docs:

• Sidebar navigation: _data/navigation.yml
• Page layout template: _layouts/default.html
• Stylesheet: assets/css/main.css
• Search index: search.json
• JSON API: api/reference.json
• Format-specific headline formula blocks: _includes/headline-formulas/[match].html—one file per format; order on the Headlines page follows _data/navigation.yml automatically

Versioning and Changelog

The site uses semantic-style versioning: [MAJOR.MINOR.PATCH]

• PATCH—minor corrections, clarifications, or small additions within an existing section
• MINOR—new subsection, new format page, new guidance block, or meaningful expansion of an existing section
• MAJOR—structural changes, new top-level sections, or significant policy shifts

Every change is recorded in the Changelog with the version number, month, and a description of what changed and why. The current version is always the first entry.

Technical Stack

The site generates two machine-readable outputs at build time:

• /api/reference.json—structured section index with IDs, statuses, and URLs
• /search.json—full-text search index consumed by Lunr.js on the search page