Documentation
¶
Overview ¶
Package mdext is mdoc's goldmark extension. It adds markdown-native document apparatus: auto section numbering, a `:::toc` table of contents, `[@key]` citations, and a `:::bibliography` reference list — so the body stays markdown instead of hand-written HTML.
The extension is constructed per render with the document's frontmatter (see New); a single AST transformer builds the document model and the node renderers emit a stable `mdoc-*` CSS-class contract that themes style.
Index ¶
- Variables
- func New(cfg Config) goldmark.Extender
- func NewCitationParser() parser.InlineParser
- func NewDirectiveParser() parser.BlockParser
- func NewIDs() parser.IDs
- func NewNodeRenderer() renderer.NodeRenderer
- type BibEntry
- type Caption
- type CaptionEntry
- type CaptionLabel
- type Captioned
- type Citation
- type Config
- type Directive
- type HeadingEntry
- type Matter
- type SecNum
- type Xref
Constants ¶
This section is empty.
Variables ¶
var KindCaption = gast.NewNodeKind("Caption")
KindCaption is the NodeKind of a Caption node.
var KindCaptionLabel = gast.NewNodeKind("CaptionLabel")
KindCaptionLabel is the NodeKind of a CaptionLabel node.
var KindCaptioned = gast.NewNodeKind("Captioned")
KindCaptioned is the NodeKind of a Captioned node.
var KindCitation = gast.NewNodeKind("Citation")
KindCitation is the NodeKind of a Citation node.
var KindDirective = gast.NewNodeKind("Directive")
KindDirective is the NodeKind of a Directive node.
var KindMatter = gast.NewNodeKind("Matter")
KindMatter is the NodeKind of a Matter node.
var KindSecNum = gast.NewNodeKind("SecNum")
KindSecNum is the NodeKind of a SecNum node.
var KindXref = gast.NewNodeKind("Xref")
KindXref is the NodeKind of an Xref node.
Functions ¶
func New ¶
New returns a goldmark extender for the given document config. Build it per Convert so it sees that document's references and numbering.
func NewCitationParser ¶
func NewCitationParser() parser.InlineParser
NewCitationParser returns the `[@key]` / `[#id]` inline parser.
func NewDirectiveParser ¶
func NewDirectiveParser() parser.BlockParser
NewDirectiveParser returns the `:::…` directive block parser.
func NewIDs ¶
NewIDs returns a transliterating parser.IDs. Pass it via parser.NewContext(parser.WithIDs(NewIDs())) at Convert time.
func NewNodeRenderer ¶
func NewNodeRenderer() renderer.NodeRenderer
NewNodeRenderer returns the renderer for Directive, Citation and SecNum nodes.
Types ¶
type Caption ¶
Caption holds the caption of a Captioned block. It carries inline children (the injected label followed by the author's rich caption text) and renders as a `<figcaption>`.
type CaptionEntry ¶
type CaptionEntry struct {
Number string // "2.1" / "A.1"
Title string // plain caption text (falls back to the image alt)
ID string
}
CaptionEntry is one collected figure or table, used to build a list of figures (`:::lof`) or tables (`:::lot`).
type CaptionLabel ¶
type CaptionLabel struct {
gast.BaseInline
Label string
Class string
}
CaptionLabel is the "Abbildung 2.1" / "Tabelle 2.1" lead injected as a caption's first inline child. Class selects the per-variant CSS class. The field is Label (not Text) to avoid shadowing ast.Node's Text method.
func NewCaptionLabel ¶
func NewCaptionLabel(label, class string) *CaptionLabel
NewCaptionLabel returns a CaptionLabel with the given text and CSS class.
func (*CaptionLabel) Dump ¶
func (n *CaptionLabel) Dump(source []byte, level int)
Dump implements ast.Node.Dump.
func (*CaptionLabel) Kind ¶
func (n *CaptionLabel) Kind() gast.NodeKind
Kind implements ast.Node.Kind.
type Captioned ¶
type Captioned struct {
gast.BaseBlock
Variant string // "figure" | "table"
ID string
Number string
Options map[string]string
}
Captioned is a `:::figure … :::` or `:::table … :::` block. Its body is normal markdown: image-bearing paragraphs (or a table) are the media, the remaining text paragraphs are the caption. The transformer numbers it, separates media from caption (a Caption child), and injects the "Abbildung 2.1" label.
func NewCaptioned ¶
NewCaptioned returns a Captioned of the given variant.
type Citation ¶
type Citation struct {
gast.BaseInline
Key string
Locator string
Number int
RefID string
Resolved bool
}
Citation is an inline `[@key]` (optionally `[@key, locator]`). The transformer fills Number/RefID/Resolved.
func NewCitation ¶
NewCitation returns a Citation for the given key and optional locator.
type Config ¶
type Config struct {
References []document.Reference
Numbering document.Numbering
// Labels maps a captioned variant ("figure"/"table") to its caption word,
// e.g. {"figure": "Abbildung", "table": "Tabelle"}. Empty entries fall back
// to the English defaults.
Labels map[string]string
}
Config parameterises the extension with the document's frontmatter.
type Directive ¶
type Directive struct {
gast.BaseBlock
Name string
Arg string // trailing token on the open line, e.g. `:::page cover`
Options map[string]string
Headings []HeadingEntry
Bib []BibEntry
Entries []CaptionEntry
}
Directive is a single-line `:::name [arg] [key=value …]` leaf block (toc, bibliography, lof, lot, page, and the matter markers). The block parser fills Name/Arg/Options; the AST transformer fills Headings (name=="toc"), Bib (name=="bibliography"), or Entries (name=="lof"/"lot") so the renderer can emit them without a parser.Context.
func NewDirective ¶
NewDirective returns a Directive with the given name.
type HeadingEntry ¶
type HeadingEntry struct {
Level int
Number string // "2.1" / "A.1"; empty when the heading is {.unnumbered}
Title string // plain text, without the number
ID string
}
HeadingEntry is one collected heading, used to build a table of contents.
type Matter ¶
Matter is a document region (front matter / main matter / appendix). The transformer creates it by wrapping the nodes between two matter markers (`:::frontmatter` / `:::mainmatter` / `:::appendix`); it renders as a `<div class="mdoc-matter-<kind>">` the theme can style and break on.
type SecNum ¶
type SecNum struct {
gast.BaseInline
Num string
}
SecNum is the section number injected as a numbered heading's first inline child, e.g. the "2.1" in "<h2>2.1 Title</h2>".
type Xref ¶
type Xref struct {
gast.BaseInline
ID string
Mode string // "num" | "page"
Number string
Resolved bool
}
Xref is an inline cross-reference `[#id]` (the target element's number) or `[#id page]` (its page number, resolved by the theme via target-counter). The transformer fills Number/Resolved.