mdext

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 21, 2026 License: MIT Imports: 11 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var KindCaption = gast.NewNodeKind("Caption")

KindCaption is the NodeKind of a Caption node.

View Source
var KindCaptionLabel = gast.NewNodeKind("CaptionLabel")

KindCaptionLabel is the NodeKind of a CaptionLabel node.

View Source
var KindCaptioned = gast.NewNodeKind("Captioned")

KindCaptioned is the NodeKind of a Captioned node.

View Source
var KindCitation = gast.NewNodeKind("Citation")

KindCitation is the NodeKind of a Citation node.

View Source
var KindDirective = gast.NewNodeKind("Directive")

KindDirective is the NodeKind of a Directive node.

View Source
var KindMatter = gast.NewNodeKind("Matter")

KindMatter is the NodeKind of a Matter node.

View Source
var KindSecNum = gast.NewNodeKind("SecNum")

KindSecNum is the NodeKind of a SecNum node.

View Source
var KindXref = gast.NewNodeKind("Xref")

KindXref is the NodeKind of an Xref node.

Functions

func New

func New(cfg Config) goldmark.Extender

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

func NewIDs() parser.IDs

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 BibEntry

type BibEntry struct {
	Number int
	Key    string
	Ref    document.Reference
}

BibEntry is one numbered, cited reference, used to build a bibliography.

type Caption

type Caption struct {
	gast.BaseBlock
}

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>`.

func NewCaption

func NewCaption() *Caption

NewCaption returns an empty Caption.

func (*Caption) Dump

func (n *Caption) Dump(source []byte, level int)

Dump implements ast.Node.Dump.

func (*Caption) Kind

func (n *Caption) Kind() gast.NodeKind

Kind implements ast.Node.Kind.

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

func NewCaptioned(variant string) *Captioned

NewCaptioned returns a Captioned of the given variant.

func (*Captioned) Dump

func (n *Captioned) Dump(source []byte, level int)

Dump implements ast.Node.Dump.

func (*Captioned) Kind

func (n *Captioned) Kind() gast.NodeKind

Kind implements ast.Node.Kind.

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

func NewCitation(key, locator string) *Citation

NewCitation returns a Citation for the given key and optional locator.

func (*Citation) Dump

func (n *Citation) Dump(source []byte, level int)

Dump implements ast.Node.Dump.

func (*Citation) Kind

func (n *Citation) Kind() gast.NodeKind

Kind implements ast.Node.Kind.

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

func NewDirective(name string) *Directive

NewDirective returns a Directive with the given name.

func (*Directive) Dump

func (n *Directive) Dump(source []byte, level int)

Dump implements ast.Node.Dump.

func (*Directive) Kind

func (n *Directive) Kind() gast.NodeKind

Kind implements ast.Node.Kind.

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

type Matter struct {
	gast.BaseBlock
	Region string // "front" | "main" | "appendix"
}

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.

func NewMatter

func NewMatter(region string) *Matter

NewMatter returns a Matter region of the given kind.

func (*Matter) Dump

func (n *Matter) Dump(source []byte, level int)

Dump implements ast.Node.Dump.

func (*Matter) Kind

func (n *Matter) Kind() gast.NodeKind

Kind implements ast.Node.Kind.

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>".

func NewSecNum

func NewSecNum(num string) *SecNum

NewSecNum returns a SecNum carrying the given number text.

func (*SecNum) Dump

func (n *SecNum) Dump(source []byte, level int)

Dump implements ast.Node.Dump.

func (*SecNum) Kind

func (n *SecNum) Kind() gast.NodeKind

Kind implements ast.Node.Kind.

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.

func NewXref

func NewXref(id, mode string) *Xref

NewXref returns an Xref to the given id in the given mode ("num" | "page").

func (*Xref) Dump

func (n *Xref) Dump(source []byte, level int)

Dump implements ast.Node.Dump.

func (*Xref) Kind

func (n *Xref) Kind() gast.NodeKind

Kind implements ast.Node.Kind.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL