Grapharch documentation graph
Documentation graph specification
One graph, several publications
A documentation graph connects subjects, authored prose, generated explanations, and publication instructions. A website and a review document can reuse that content while arranging it differently.
Read one graph in two ways
The reader website emphasizes navigation. The review document provides a contents page, numbered sections, appendices, and references. The shared fragments retain their identities in both outputs.
- Collect source content through small, specialized adapters.
- Assemble complete contributions into a validated revision.
- Resolve each target against that revision before rendering.
An incomplete update must not replace a complete publication. A newer accepted rendering request supersedes older work.
The publication contract and glossary are linked from the same documentable subjects in both formats.
Documentation vocabulary
The following table deliberately crosses page boundaries in the review document. Its header should repeat, its cells should wrap, and every row should remain legible.
| Term | Meaning |
|---|---|
| Documentable subject | An identified resource that can be explained by authored and generated fragments. |
| Authored fragment | Narrative supplied by an editor and retained as content independent of output layout. |
| Generated fragment | An explanation derived from collected assertions, with a traceable subject and source. |
| Collector instance | A configured adapter for one specific kind of input, with its own contribution ownership. |
| Subject scope | A reusable selection that includes subjects, applies exclusions, and bounds relationship traversal. |
| Logical component | A meaningful unit such as an introduction, definition, example, glossary, or reference list. |
| Placement | A target-specific position for a logical component. It does not change the shared fragment. |
| Publication profile | An arrangement and presentation definition that can be reused by several targets. |
| Publication target | One named output binding a scope, profile, renderer, and artifact destination. |
| Validated revision | A pinned set of complete contributions that passed the project definition checks. |
| Graph writer | The coordinator receiving bounded contribution chunks from concurrent producers. |
| Contribution chunk | A limited piece of normalized RDF that remains private until the contribution completes. |
| Stable identity | An identifier that does not change merely because a render job or process restarts. |
| External reference | An explicitly identified resource whose documentation is published outside this target. |
| Source provenance | The relationship connecting content to its project, processor instance, and native source. |
| Source revision | The observed input state used to decide whether generated content can be reused. |
| Scope exclusion | An instruction removing a subject from the selected publication membership. |
| Traversal boundary | An explicit limit preventing relationship expansion from consuming an entire connected graph. |
| Web anchor | A fragment destination derived from target, placement, and shared content identities. |
| Reading order | The sequence selected for a publication; it need not match website navigation. |
| Glossary entry | A concise explanation of terminology used by the publication. |
| Appendix | Supplementary material presented separately from the main numbered sections. |
| Reference list | A collection of links identifying the standards and sources used by the document. |
| Publication job | One rendering attempt whose result and provenance are recorded in the shared dataset. |
| Manifest | The ownership and provenance record accompanying a completed set of artifacts. |
| Draft preview | An authoring view that retains the last successful output when a new render fails. |
| Revision comparison | A future view explaining the changes between two explicitly selected graph revisions. |
| Static deployment | Publication of generated files without requiring Grapharch to serve reader requests. |
A source assertion stays data
An RDF assertion can be documented without turning the documentation body into executable Typst.
<urn:example:fragment> <urn:example:subject> <urn:example:ontology> .
#panic("This line is displayed as source text, never evaluated.")
Literal brackets such as [subject], quotation marks, and the # character remain visible. Return to the vocabulary table.
Appendix A. Publication contract
Required publication behaviour
- Read a complete, validated source revision.
- Resolve references to included content or explicit external resources.
- Write a new generation without changing the visible output.
- Promote only the latest accepted request for that target.
- Keep artifacts belonging to other targets and user-owned files intact.
This appendix is intentionally placed after the main content in the specification and after the reference list in the reader website.
Glossary
- Contribution - Normalized assertions owned by one source-processing attempt.
- Fragment - Shared authored or generated content describing an identified subject.
- Plan - A resolved target arrangement pinned to a validated graph revision.
- Target - One requested output, such as a reader website or review document.