This entire product site is authored, validated, and rendered with Sights.See how it works
Menu

Content contracts

Content stays meaningful because implementation stays out.

A Sights page names the route, metadata, sections, and content each section needs. It cannot carry raw HTML, CSS classes, styles, scripts, secrets, or executable expressions.

Follow the authoring workflow
A concise page JSON file connected to schema validation, a generated catalog, and a safe result

Small surface, complete model

Pages describe intent, not rendering instructions.

Composed pages contain an ordered list of named sections. Templated pages select one validated record and resolve it into the same section model before rendering.

Long-form prose lives in local Markdown sidecars. Reusable records—such as posts and people—live in typed collections. The route graph checks the relationships between all of them.

  • Stable identityPages, sections, records, and routes use explicit ids so diffs and references remain legible.
  • Strict fieldsUnknown component names, props, page fields, and collection shapes fail validation instead of disappearing at render time.
  • Safe proseMarkdown supports useful CommonMark while rejecting raw HTML, unsafe protocols, and remote image dependencies.

Before rendering

Validation follows the whole site graph.

A syntactically valid file is not enough. Sights checks whether every referenced part of the site actually exists and can be published safely.

  1. Parse the source

    Load strict JSON, local Markdown, collection records, site configuration, and the active theme.

  2. Validate each contract

    Apply the page, component, template, collection, image, action, and theme schemas with unknown fields rejected.

  3. Resolve references

    Materialize collection-backed props and templates into the same ordinary section model used by composed pages.

  4. Check the graph

    Verify routes, links, fragments, assets, breadcrumbs, public visibility, and record destinations across the site.

  5. Explain the failure

    Report the source file, JSON Pointer, invalid value, expected shape, and a useful correction before Astro renders.

Agent-readable by construction

The system publishes its own local operating manual.

Generated artifacts make the valid editing surface discoverable without relying on a stale prompt or undocumented conventions.

  • Agent guide

    A generated reference explains decision order, authoring rules, prohibited content, runtime boundaries, and every component.

  • JSON Schemas

    Page, theme, component, collection, and template schemas support editors and machine authors directly.

  • Component catalog

    Machine-readable entries expose purpose, variants, examples, accessibility needs, runtime declarations, and usage guidance.

  • Template catalog

    Registered record templates document their data contracts and the situations where they should or should not be used.

  • Primitive catalog

    Trusted implementers can discover the lower-level layout and image tools without exposing them as arbitrary page-builder blocks.

  • Inspection output

    Development pages can return the validated resolved model so reviewers and tools see what actually powers the render.

Content questions

What authors can—and cannot—put in a page.

Why JSON instead of asking an agent to write Astro or React?

JSON makes the valid choices finite, schema-checkable, and easy to review. The component already owns markup and responsive behavior, so most page changes do not need application code.

Where does long-form copy live?

Articles, policies, and other substantial prose live in local Markdown sidecars. Sights sanitizes them at build time and rejects raw HTML and unsafe link protocols.

Can page content choose a color or CSS class?

No. Pages may select documented semantic variants such as a section tone. Literal presentation belongs in the validated theme or trusted component implementation.

Can links point anywhere?

External URLs must use an allowed protocol. Internal routes and published fragments are resolved against the full site graph, including public-versus-internal visibility.

Can an agent still add a new capability?

Yes, through trusted code: define a strict component schema, renderer, manifest, examples, and any isolated runtime. Declarative content never becomes the code boundary.

Next capability

See what those content contracts are allowed to compose.

The component system turns a small declarative page surface into a broad set of tested, responsive site patterns.

Explore the component system