Documentation
¶
Overview ¶
Package docir is a small intermediate representation for Rad's documentation. The source docs are authored in Material-for-MkDocs flavored markdown (admonitions, content tabs, result <div>s, GFM tables, HTML-comment authoring notes) because the website renders that dialect natively. None of those constructs survive a plain terminal renderer, so `rad docs` used to print them as literal noise.
docir parses a doc into a flat list of typed Blocks - dropping authoring comments along the way - and then emits a target-specific rendering. Today the only emitter is EmitTerminal, which produces clean markdown for the embedded `rad docs` corpus (consumed both rendered in a TTY and piped raw into LLM context). The block model is the seam: a future web or LLM-specific emitter is a new function over the same []Block, not a new parser.
The parser is deliberately scoped to the handful of constructs that actually appear in our corpus rather than full CommonMark - anything it doesn't model passes through verbatim as Text.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EmitTerminal ¶
EmitTerminal renders blocks back to clean markdown for the embedded `rad docs` corpus. The output is still markdown (not ANSI): the runtime renderer applies TTY styling, and piping it raw yields clean text for LLM context. Constructs the runtime renderer can't handle (admonitions, tabs, ragged tables, HTML, comments) are gone by here.
func RewriteInlineLinks ¶
RewriteInlineLinks rewrites every markdown inline link outside fenced code via resolve(text, href), which returns the replacement text. The runtime terminal renderer only auto-links bare URLs - it has no notion of `[text](href)` syntax - so web-authored links would otherwise show as literal noise (relative .md paths) or dangle. resolve turns them into something useful in a terminal (e.g. "text (rad docs <topic>)").
Links inside code blocks are left untouched (a URL in example code must survive verbatim). docir owns the mechanics; the caller supplies resolve since only it knows how hrefs map to `rad docs` topics.
Types ¶
type Align ¶
type Align int
Align is a table column alignment, parsed from the separator row's colons.
type Block ¶
type Block interface {
// contains filtered or unexported methods
}
Block is one structural element of a parsed doc.
type Callout ¶
Callout is an admonition (`!!! info "Title"`). Body is parsed recursively, so a code block inside an admonition is a real Code block, not escaped text.
type Code ¶
Code is a fenced code block. Lang is the first token of the fence info string (mkdocs extras like `linenums="1"` are dropped). IsResult marks a block that was wrapped in <div class="result"> - i.e. example output rather than input.
type Table ¶
Table is a GFM table. Cells are stored verbatim (backticks and all); the terminal emitter pads them into aligned columns so they read in a terminal instead of as a ragged pipe soup.
type Tabs ¶
type Tabs struct {
Tabs []Tab
}
Tabs is a content-tab group (`=== "Bash"` ...). On the web these render as interactive tabs; in a terminal there's no tabbing, so we flatten them to labeled sections.
type Text ¶
type Text struct {
Lines []string
}
Text is the passthrough block: prose, headings, lists, thematic breaks, blank lines, and any markup docir doesn't specially model. Inline markdown inside the lines is left untouched - styling it is the terminal renderer's job at runtime. Lines have leading/trailing blank lines trimmed and internal blank runs collapsed to one.
Source Files