Proposal: Render specifications as HTML for human review

[mheadd]

Summary

SpecOps specifications are currently written and stored as Markdown. This proposal suggests keeping Markdown as the source format while adding a build step that renders specs into styled, interlinked HTML — optimized for the human review that is central to the methodology.

This is a request for community input, not a decided direction. I'd love to hear what you think.

Motivation

SpecOps Principle 3 says domain experts (policy people, program administrators, business stakeholders) are the arbiters of correctness. These reviewers are the primary audience for specifications, yet they currently receive a format designed for developers.

A well-structured HTML rendering could make the review experience significantly better without giving up the benefits of Markdown as a storage and authoring format.

What is being proposed

Markdown remains the source of truth. Specs continue to be authored, versioned, and stored as Markdown files in git. Diffs stay clean, agents consume them efficiently, and anyone can contribute.

A build step renders specs into styled HTML for review. The HTML output would be the artifact domain experts actually read and verify during Phase 3 (Specification Verification).

Benefits of rendering to HTML

Better readability for non-technical reviewers

Styled HTML with clear visual hierarchy, collapsible sections, and highlighted business rules is dramatically easier to review than raw Markdown — especially for policy experts who may need to verify hundreds of pages of specification.

Navigable cross-module links

Spec modules frequently reference each other (e.g., eligibility rules reference benefit calculations). Standard hyperlinks with anchor-level precision create a navigable web of interconnected specifications that mirrors how the systems themselves are interconnected.

Richer semantic structure

HTML elements like <details>, <aside>, <section>, and <table> can express document structure in ways Markdown’s flat heading hierarchy cannot. An agent or reviewer could distinguish a sidebar note from a core business rule based on the markup.

Structured metadata

HTML supports data-* attributes and <meta> tags that could embed machine-readable metadata directly in the rendered spec: module IDs, legacy source references, verification status, policy citations, last-reviewed-by — without a separate metadata file.

Review workflow affordances

The HTML view could include visual status indicators (verified/unverified), collapsible sections for different review states, and navigation aids. This directly supports the verification phase described in the Methodology.

Accessibility

Proper HTML semantics, ARIA attributes, and landmark regions provide a mature accessibility story — important when reviewers may include people using assistive technology, and aligned with federal compliance requirements.

Risks and tradeoffs to consider

Added build complexity

A Markdown-to-HTML pipeline introduces tooling that every adopting agency would need to run or integrate into their workflow. This needs to be simple and well-documented.

Maintaining the Markdown ↔ HTML relationship

If reviewers want to suggest changes, they need a path back to the Markdown source. The rendered HTML should make it easy to locate the corresponding source file and section.

Scope creep into presentation

HTML invites styling and layout polish. We’d need to be disciplined about keeping the focus on content correctness, not visual design. A standardized template/theme would help.

Token cost for agents

If agents ever need to consume the HTML rather than the Markdown source, the additional markup increases token usage. The proposal avoids this by keeping Markdown as the agent-facing format, but the boundary needs to be clear.

Prior art in this repo

This project already renders its own documentation site from source files to HTML (see the docs/ directory and build scripts). This existing infrastructure serves as a small-scale proof of concept for the approach.

Questions for the community

1. Does this match your experience? Have you found Markdown specs difficult for non-technical reviewers to work with?
2. Source format concerns? Are there use cases where Markdown as source would be limiting — or where HTML as source would be preferable?
3. Tooling preferences? If we build this, what static site / doc rendering tools would work well? (Eleventy, Hugo, Docusaurus, something custom, etc.)
4. Metadata schema? What metadata would be most valuable to embed in rendered specs? (Verification status, policy references, legacy source mapping, etc.)
5. Review workflow integration? How do you envision domain experts interacting with the rendered HTML — just reading, or also annotating/commenting?
6. Risks we have not considered? What could go wrong?

Please share your thoughts, questions, and concerns. Thanks!