generated from coulomb/repo-seed
97 lines
3.5 KiB
Markdown
97 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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.
|