# 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. ## 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](https://csa-content-standards.pierce.tools) **Repository:** [github.com/{{ site.github_username }}/{{ site.github_repo }}](https://github.com/{{ site.github_username }}/{{ site.github_repo }}) **JSON API:** [/api/reference.json](/api/reference.json) --- ## Content Sections The site is organized into eleven numbered sections plus supporting reference pages. | # | Section | What it covers | |---|---|---| | 1 | [General Guidelines]({{ "/docs/brand-guidelines" | relative_url }}) | Universal rules—voice and tone, headlines, explicit language, internal links, bylines, AI disclosure, Helpful Content standard, compliance. Applies to all formats and platforms unless explicitly overridden. | | 2 | [Headlines]({{ "/docs/headlines" | relative_url }}) | Outlet-specific headline standards and all format-specific headline formulas—character counts, casing, formula variations, and no-verb exceptions by format. | | 3 | [Article Formats]({{ "/docs/what-to-know-next" | relative_url }}) | Format-specific rules for each article type—structure, metadata, word count, image specs, URL patterns, tags, and pre-publish checklists. Twelve formats are documented (3 active, 8 pending, 1 retired). | | 4 | [Personas]({{ "/docs/discover-browser" | relative_url }}) | Audience definitions used to guide tone, framing, and content decisions. Five personas are currently active: The Discover Browser, The Curious Optimizer, The Wonder-Driven Science Enthusiast, The Curious Explorer, and The Watercooler Insider. Each persona page includes a **CSA Target Audience Definition** section at the bottom—the formatted definition for direct entry into the CSA product UI. | | 5 | [Acceptable Sources]({{ "/docs/acceptable-sources" | relative_url }}) | Approved source categories and specific outlets for factual reporting and citation across all verticals. | | 6 | [Publishing Guidelines]({{ "/docs/publishing-guidelines" | relative_url }}) | Platform-specific CMS entry requirements—CUE (McClatchy CMS), WordPress, Apple News, and additional export destinations. | | 7 | [Follow-Up Content]({{ "/docs/follow-up-content" | relative_url }}) | Editorial strategy for extending breaking news coverage—decision framework and follow-up angle guide for 13 story types. | | 8 | [AI Tool Responsibility]({{ "/docs/tool-responsibility" | relative_url }}) | Policy and escalation procedures for all team members using the CSA or any AI-assisted tool—single-piece concerns, supervisor conflict, recurring issues, plagiarism, partner content, and override documentation. | | 9 | [Claims Validation]({{ "/docs/claims-validation" | relative_url }}) | Ideal-state specification for the CSA fact-checking module—verdict taxonomy, editorial action framework, source authority tiers, source count requirements, content-type rules, escalation logic, audit trail, and override tracking. | | 10 | [Platform Guidance]({{ "/docs/platform-smartnews" | relative_url }}) | External rule-sets that constrain output beyond General Guidelines: distribution-platform requirements (SmartNews §10.1, Apple News §10.2), per-publication style guides (Us Weekly §10.3, Trend Hunter B2C §10.4, Woman's World §10.5), and AP-Compatible §10.6 (Quick / Condensed / Thorough tiers). | | 11 | [Layered Enforcement]({{ "/docs/layered-enforcement" | relative_url }}) | Conceptual model + machine-readable rules contract for layered style guidance enforcement. Defines how General → Persona → Format → Platform layers compose + how conflicts resolve. Companion: [Conflict Register]({{ "/docs/conflict-register" | relative_url }}) (every known cross-layer rule). Schema + algorithm + register at `_data/rules/`. | --- ## 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. | Format | Section | Status | Page | |---|---|---|---| | Everything to Know | §3.2 | ✅ Active | [everything-to-know]({{ "/docs/everything-to-know" | relative_url }}) | | FAQ / Service Journalism | §3.11 | ✅ Active | [faq]({{ "/docs/faq" | relative_url }}) | | What to Know Next | §3.12 | ✅ Active | [what-to-know-next]({{ "/docs/what-to-know-next" | relative_url }}) | | Recipe | §3.3 | 📝 Pending | [recipe]({{ "/docs/recipe" | relative_url }}) | | Timeline | §3.4 | 📝 Pending | [timeline]({{ "/docs/timeline" | relative_url }}) | | Interview | §3.5 | 📝 Pending | [interview]({{ "/docs/interview" | relative_url }}) | | Recap | §3.6 | 📝 Pending | [recap]({{ "/docs/recap" | relative_url }}) | | Fan Theory / Fan Question | §3.7 | 📝 Pending | [fan-content]({{ "/docs/fan-content" | relative_url }}) | | Obituary | §3.8 | 📝 Pending | [obituary]({{ "/docs/obituary" | relative_url }}) | | Couple / Baby | §3.9 | 📝 Pending | [couple-baby]({{ "/docs/couple-baby" | relative_url }}) | | Cast Introduction / Update | §3.10 | 📝 Pending | [cast]({{ "/docs/cast" | relative_url }}) | | Google Discover Explainer | §3.1 | 🗄️ Retired (2026-05-28) | [discover-explainer]({{ "/docs/discover-explainer" | relative_url }}) | --- ## 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: ```yaml 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: ```html ``` 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** | Tag | What it covers | |---|---| | `general-style` | General style for all work—voice, tone, vocabulary, explicit language policy, anchor text rules | | `headline` | H1 headline guidance, abstracted from SEO—character count, formula, verb requirement, modifier rules | | `seo` | SEO title, focus keyphrase, meta description, promo title | | `csa-target-audience` | Formatted persona definitions for direct entry into the CSA product UI—Name, Description, Focus areas. Appears only on §4 persona pages. | | `human-only` | Human editorial workflows—not consumed by any CSA agent at this stage | **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 `` comments to every section. The [General Guidelines page]({{ "/docs/brand-guidelines" | relative_url }}) 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]({{ "/docs/headlines" | relative_url }}) 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/.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]({{ "/docs/master-reference" | relative_url }}) 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](/api/reference.json) 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]({{ "/docs/changelog" | relative_url }}) with the version number, month, and a description of what changed and why. The current version is always the first entry. --- ## Technical Stack | Layer | Technology | |---|---| | Static site generator | [Jekyll](https://jekyllrb.com/) | | Hosting and deployment | Cloudflare Pages (private)—auto-deploys on push to `main`; GitHub Pages disabled (`has_pages: false`) since the 2026-04-23 migration | | Editing | Markdown files in `/docs`; edit via GitHub web UI or local clone + push | | Access control | Gated by GitHub authentication (only repo collaborators can view) | | Search | [Lunr.js](https://lunrjs.com/)—client-side, no external service | | Source control | GitHub—`github.com/{{ site.github_username }}/{{ site.github_repo }}` | | Markup | Markdown (CommonMark) with Jekyll Liquid templating | 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