Center for Federal Accountability › Reports

Documentation.AI MDX Template Contract

Standard hub + detail MDX structure used to publish FederalRegister report collections on the CFA reports site.

This repo generates Documentation.AI MDX for FederalRegister-derived report collections. To keep a consistent user experience, every generated hub and detail page must follow the same structural contract.

Contract goals

• Predictable navigation: hubs always link to “current” lists and back from detail pages.
• Consistent scannability: each page renders the same header sections in the same order.
• MDX safety: generated descriptions must be tag-safe so Documentation.AI does not interpret user-provided text as JSX/HTML.

Shared frontmatter (required)

Every generated page must include:

• title (string, human-readable)
• description (string, short; must be MDX/JSX-safe: no <...> markup in the description text)
• report_type (string, used by Documentation.AI dimensions/filters)
• persona (string; typically all)

Hub pages (collection hubs)

Hub route pattern:

docs/reports/<report-type-slug>/index.mdx

Hub content sections (minimum required):

1. ## Summary
   • Include metric counts and an export timestamp.
2. ## Audience filters
   • Explain which Documentation.AI dimensions can be used to filter and what the user can expect.
   • Use an <ExpandableGroup> block when the methodology is long.
3. ## Navigation
   • Links to:
     • current list page (/docs/reports/<report-type-slug>/current/index)
     • archive page (/docs/reports/<report-type-slug>/archive/index) when supported
     • the report types catalog (/docs/reports/index)

Detail pages (item drill-down)

Detail route pattern:

docs/reports/<report-type-slug>/current/<items>/<slug>.mdx

Detail content sections (minimum required):

1. ## Metadata
   • A table of canonical identifiers and relevant source URLs.
2. ## Overview
   • A short, tag-safe narrative summary.
3. ExpandableGroup for “analysis / interpretation”
   • The generator must include exactly one <ExpandableGroup> with at least one <Expandable title="..."> block.
   • For analyses that already exist (e.g. open comment CFA draft), this section contains the analysis/draft content.
   • For reports that are aggregations (e.g. per-agency counts), the expandable block must contain the key findings and interpretation.
4. Back to list
   • A link back to the report hub’s current list.

Expandable naming conventions (recommended)

To keep UI labels consistent, generators should use:

• <Expandable title="Key findings" ...> for interpretive content.
• <Expandable title="Full analysis" ...> for expanded analysis when available.
• For CFA-comment-like content, keep the label:
  • CFA analysis and draft

MDX safety rules (required)

• Do not allow raw <...> to appear in description frontmatter.
• Strip markup and escape stray < before writing MDX.
• Use fenced blocks when embedding raw text blobs so MDX does not interpret them as HTML/JSX.