Render Reference And Asset Manifest Contract

Markitect models render-aware structure before an optional renderer runs. The contract is passive: it records units, requested references, static assets, and source maps, but it does not assign final numbering, rewrite links, copy assets, or validate renderer output directories.

Contract Version

markitect.render.reference.v1

The manifest kind is:

render-reference-manifest

Render Units

RenderUnitReference gives a stable identity to renderable content:

Unit kind	Typical use
`section`	Headings and TOC entries.
`figure`	Images, charts, diagrams, and captions.
`table`	Markdown or generated tables.
`equation`	Math blocks or equation-like units.
`code-block`	Numbered or referenced code listings.
`custom`	Project-defined numbered units.

The unit model may carry labels, captions, anchors, source spans, content hashes, and numbering intent such as scope or sequence. It intentionally does not carry final numbers.

Cross-References And TOC Planning

RenderCrossReference represents a requested link from one source location to a target render unit. It records the target unit and requested style, while the renderer decides final label text, numbering, and URL rewriting.

RenderTocEntry records planned table-of-contents entries by unit id, title, level, parent id, and order. The renderer owns final page numbers and links.

Static Assets

RenderAssetManifest is a deterministic list of static assets referenced by renderer source. Each RenderAsset records:

source URI or source path
name, media type, and extension
digest when available
logical role
copy policy declaration
renderer output reference placeholder
provenance back to source spans or source adapter attachments

Supported copy policies are copy, embed, link, preserve, and skip. They are declarations for downstream renderers. Core Markitect never copies the asset.

markitect-filter may provide read-side attachment metadata, such as source URI, path, media type, extension, digest, and attachment provenance. Markitect can transform that metadata into a render asset entry without making markitect-filter responsible for rendering.

Source Maps

RenderSourceMap connects Markitect source spans or generated function outputs to renderer units and artifact references. This is the bridge from deterministic Markdown processing to renderer-owned artifacts:

source span / function output -> render unit -> renderer source or artifact

The map can reference a Markitect source unit, a document function run, a render unit id, an artifact id, or a renderer-owned artifact reference.

Fake Renderer Integration

RenderExportRequest accepts an optional render_manifest. The built-in render.fake adapter echoes the manifest id, asset manifest id, unit counts, cross-reference count, TOC count, source-map count, and asset count into result and artifact metadata. It still performs no external rendering and has no filesystem or network side effects.

See examples/render/render-reference-manifest.yaml for a complete manifest fixture.

Repository Boundary

markitect-tool owns these passive contracts and fake-renderer metadata integration.
markitect-filter owns read-side source asset and attachment metadata.
markitect-quarkdown owns concrete Quarkdown execution, final numbering, output paths, link rewriting, asset copying, and artifact validation.

3.5 KiB Raw Permalink Blame History