Content groups and callouts
GraphArch's Markdown collector recognizes Material-style content tabs (===),
admonitions (!!!), and collapsible admonitions (???, or ???+ initially
expanded). Headers have a quoted title; admonition titles are optional. Bodies
use four-space indentation and can contain ordinary Markdown or nested groups.
Fenced and indented code examples are preserved literally.
=== "Business audience"
An explanation for business readers.
!!! tip "Start small"
Choose one use case.
=== "Technical audience"
??? note "Implementation detail"
Detail that can be expanded on the website.
Collection normalizes these constructs into a typed content-boundary model stored in the KG Markdown fragment. The model describes alternatives, alternative titles, admonition categories, and disclosure state. Ordinary Markdown remains between the boundaries, so links, images, headings, and provenance use the normal collection pipeline. Rendering never rereads the source file or requires MkDocs.
HTML presents alternatives as keyboard-accessible tabs, with arrow, Home, and
End navigation. Without JavaScript, every alternative remains visible.
Collapsible admonitions use native details/summary controls. PDF presents every
selected alternative in order under its title, and expands all selected
admonition content. inline and end source presentation hints are accepted;
they do not impose floating text on the output.
The retained boundary format is a grapharch-content fenced JSON record with a
kind: alternatives, alternative, admonition, or end. Titles and category
names are data, never executable HTML or CSS. Records are validated and nested
boundaries must balance. This format is collector output, not required authoring
syntax.
Selecting a heading inside a group preserves its enclosing context through
ga:contentPrefix and ga:contentSuffix. The selected fragment body stays an
unchanged slice of the normalized document. Independent rendering applies that
context; whole-page reconstruction joins the original bodies without splitting
one original group into several groups.
Limits are explicit: 1 MiB source Markdown, 256 containers, 16 nesting levels, 512-byte titles, and 64-byte category names. Invalid titles, unknown header options, missing indented bodies, malformed boundary records, and unbalanced containers fail rather than silently appearing as ordinary text.
Included source fragments
Local Markdown collectors accept --8<-- "path.md" and
{% include-markdown "path.md" start="<!--start-->" end="<!--end-->" %}.
Markers are optional, excluded from the selected text, and must occur exactly
once when supplied. Nested includes preserve indentation and rebase relative
inline links and images to the including page. Reference-style relative links
inside includes currently require conversion to inline link syntax.
Paths resolve against the documentation content root and explicitly configured
include roots. They never resolve against the process working directory.
MarkdownFile::with_include_roots adds up to eight roots; ambiguous matches,
absolute paths, parent traversal, symlink escapes, cycles, unknown directive
options, and missing markers fail collection. Each included source is limited
to 256 KiB, all dependencies to 1 MiB, nesting to 16 levels, and dependencies
to 128 per page. Supplied Git blobs require a repository-aware include resolver
and cannot use this local-file mechanism.
The collected contribution retains full included source text and its hash,
selected character ranges, and prov:wasDerivedFrom links. Updates outside a
selected range still change dependency provenance. Publication reads the
expanded Markdown from the pinned KG, so exporting the KG and deleting source
files does not lose included content. Abbreviation definitions included from
MkDocs sources do not imply support for MkDocs abbreviation expansion.
Identifier badges
An authored empty objective-badge span with an alphanumeric data-letter
becomes a semantic inline identifier. A letter_prefix frontmatter value adds
the same identifier to the first level-one heading. Identifiers contain 1–16
ASCII letters or digits; they do not change heading anchors or navigation titles.
The optional source class objective-badge-sm does not dictate output styling.
The retained Markdown spelling is an empty link to
urn:grapharch:badge:IDENTIFIER. This is an identifier annotation, not a
navigational URL. Shared HTML and PDF renderers display the identifier as a
compact label. Raw HTML is not passed through. Ordinary code examples remain
literal; invalid badge markup is handled by the normal unsupported-HTML error.
Material card collections written as <div class="grid cards" markdown> around
an ordinary Markdown list are collected as semantic card groups. HTML presents
the list as responsive cards using the shared theme; PDF retains every item in
reading order. This supports the explicit authoring construct, not arbitrary
HTML or source-owned CSS.
Figures and captions
A <figure markdown> block containing one Markdown image or table followed by one
<figcaption> becomes a semantic Figure with a Caption child. Caption text,
links, emphasis, line breaks, and copyright attribution remain ordinary
Markdown in the retained graph. HTML publishes real figure and figcaption
elements; PDF keeps the content and caption together as a figure.
An image's optional { width="700" } hint supplies a maximum width in pixels,
clamped to the available output width. Values must be 1–2048. Arbitrary figure
attributes, multiple images, absent captions, and additional figure body
content fail rather than being discarded. Literal examples inside code blocks
remain literal. There are at most 128 figures per capped Markdown source, with
captions limited to 16 KiB.
Explicit destinations
Use an empty <span id="ontology"></span> or <a id="ontology"></a>
when a durable link target belongs inside a tab or between headings. The
collector retains its identity as a semantic destination, independently of
HTML styling. Other span attributes and nonempty anchor bodies are not accepted
by this construct; literal code examples are unchanged.
Website links such as concept.md#ontology validate against both headings and
explicit destinations. A fragment link into a tab opens the relevant panel.
Duplicate IDs, including collisions with headings, fail. HTML and PDF document
outputs give destinations a component prefix so independent source sections
can use the same local identifier safely. Rendering uses the retained graph,
including after the source files have been removed.
Decorative icons
GraphArch recognizes four bundled inline icon names used by the EKGF source
sites: :octicons-arrow-right-24:, :material-cached:,
:material-floor-plan:, and :material-run:. An optional { .lg } suffix
requests a larger icon. Icons can appear inside ordinary Markdown links; the
visible text label and link destination remain authoritative. Code examples
remain literal, and an unknown Material or Octicons name produces an error.
Collection records these as empty-alt builtin image references using the
urn:grapharch:icon: namespace. HTML emits decorative, accessibility-hidden
SVGs; PDF uses the same bundled vector artwork. No icon service or browser
framework is required. Each source is limited to 128 icons, and generated
publications include grapharch-icon-licenses.txt with the artwork notices.
Footnotes
Standard Markdown notes ([^label] and [^label]: explanation) retain their
source identity when collected. Definitions needed by a selected heading or an
included excerpt travel with that content, even when authored elsewhere in the
source document. Independent source files can reuse the same authored label.
Material tabs and callouts are normalized before note identities are assigned.
HTML links numbered references to their notes. PDF uses native numbered footnotes and reuses the same note for repeated references in a fragment. Definitions can contain ordinary Markdown emphasis and links. Unused notes are omitted from selected excerpts; nested notes and conflicting definitions fail. A source is capped at 128 notes, 1,024 references, and 64 KiB per definition.