Skip to main content

Module document

Module document 

Source
Expand description

Portable document model — what engines produce. Portable document model — what engines produce.

This module defines the universal semantic shape every engine renders into. The model carries:

  • Structure: Block / InlineSpan (headings, paragraphs, lists, links, etc.) — what content there is.
  • Semantic intent: FeedHeader, FeedEntry, MetadataRow, Badge — when a source format has block-level meaning beyond “this is a paragraph”, the engine can name it. Intelligence layers downstream (search, summarise, recommend, recall) match on these intents, not just text.
  • Provenance: where the content came from (canonical URI, source engine, fetch time, source label).
  • Trust state: how authenticated the source is (Trusted / Tofu / Insecure / Broken / Unknown).
  • Diagnostics: parser / render warnings the engine wants to surface (unsupported construct, degraded rendering, parse warnings).

§Spec faithfulness

Protocol engines (gemini, gopher, RSS/Atom, finger) populate semantic variants only when the source spec actually says them — RSS <item> becomes FeedEntry, finger Login: alice becomes MetadataRow. The engines do not invent semantics the spec doesn’t say. File-format engines (markdown, the knot note format) can be richer because the format owns its own semantics.

§Round-trip

EngineDocument::to_markdown and EngineDocument::to_gemini live in the render submodule and let clips / notes export back into native CommonMark / gemtext.

Structs§

BlockEvaluators
The host’s eval menu: the BlockEvaluators it ships, keyed by language. Routing a fence’s tag to a backend is the polyglot seam — register the languages you trust on this build, and an unknown tag simply isn’t found (the evaluate pass denies it).
BlockProvenance
Provenance for a single block within an crate::EngineDocument.
BlockProvenanceMap
Sparse map from crate::EngineDocument::blocks index to a per-block provenance override.
DocumentProvenance
Where the document came from.
EngineDocument
A rendered document.
EvalOutcome
What happened: counts, reasons, and the provenance of every spliced block.
EvalOutput
What an evaluator returns: a format tag and the text it produced. plain (or empty) renders as a text block; gemtext / markdown / djot are nested-rendered through the registry.
EvaluationPolicy
What the evaluate pass may do, as plain data. The host builds one per document from its standing and the user’s settings; deny_all is the floor and the right default for any received document.
Fetched
What a fetch closure returns: the body plus the content type the transport reported (None lets the renderer sniff).
GophermapContext
Server context a gophermap is written against: the host/port columns RFC 1436 requires on every menu line.
ResolvedProvenance
Result of resolving provenance for a single block.
TranscludeOutcome
What happened, faithfully: counts and reasons, plus the provenance of every spliced block (top-level index → source), for the host to carry the way clips carry theirs.
TransclusionPolicy
What the resolve pass may do, as plain data. The host builds one per document from the document’s standing (own note vs received) and the user’s settings; TransclusionPolicy::deny_all is the safe floor.

Enums§

Block
A block-level region of an EngineDocument.
DocumentDiagnostic
A note the engine attaches to the document about parse / render quality.
DocumentTrustState
How authenticated the document’s source is.
InlineSpan
An inline-level span inside a Block.
TableAlignment
A table column’s text alignment (djot / markdown :---, :---:, ---:).

Traits§

BlockEvaluator
A pluggable knot-block evaluator: one scripting language behind the eval fence lane.

Functions§

evaluate_blocks
Run the document’s top-level <lang> eval fences in place. See the module docs for the contract; the outcome reports everything that happened.
inline_text
Flatten a span list into a plain-text string suitable for accessible names and snippet extraction. Code contributes its inner text; styling containers (Emphasis/Strong) and Link contribute their inner span text recursively. SoftBreak becomes a space, LineBreak becomes a newline.
parse_eval
Parse an eval fence’s info string: <lang> eval (the eval opt-in). Returns the language; None for a plain <lang> sample or anything else.
parse_include
Parse an include fence’s info string: include <url> (anything after the URL is reserved). Returns the URL.
resolve_transclusions
Resolve the document’s top-level include fences in place. See the module docs for the contract; the outcome reports everything that happened (and didn’t).