Documentation
¶
Overview ¶
Package markdown is mdsmith's public Markdown parse/produce surface.
It owns the one goldmark parser configuration in the tree: the default CommonMark parsers plus mdsmith's <?...?> processing- instruction block, exposed both as the high-level Parse (front matter split off, body parsed to an AST) and the lower-level ParseContext / NewParser for callers that need the goldmark parser.Context. Splice is the producer: byte-exact span surgery on the original source rather than an AST-to-Markdown re-render, so its output does not fight mdsmith's edit-based fixer.
The linter core (internal/lint) and the release tooling (internal/release) both consume this package so parsing decisions stay consistent across surfaces; internal/lint additionally re-exports the symbols here via type aliases and forwards so its many callers need not import this package directly. No code in this package imports the linter core: it depends only on goldmark and the standard library.
As a public package this is a cross-system contract. Its compatibility policy lives in docs/development/markdown-library.md.
Index ¶
- Variables
- func CountLines(b []byte) int
- func NewPIBlockParser() parser.BlockParser
- func NewParser() parser.Parser
- func PIBlockParserPrioritized() util.PrioritizedValue
- func ParseContext(src []byte, ctx parser.Context) ast.Node
- func Splice(body []byte, edits []Edit) []byte
- func StripFrontMatter(source []byte) (prefix, content []byte)
- type Document
- type Edit
- type ProcessingInstruction
Constants ¶
This section is empty.
Variables ¶
var KindProcessingInstruction = ast.NewNodeKind("ProcessingInstruction")
KindProcessingInstruction is the ast.NodeKind for ProcessingInstruction.
Functions ¶
func CountLines ¶
CountLines returns the number of newline-terminated lines in b.
func NewPIBlockParser ¶
func NewPIBlockParser() parser.BlockParser
NewPIBlockParser returns a block parser for processing instructions.
func NewParser ¶
NewParser returns mdsmith's canonical goldmark parser: the default CommonMark block, inline, and paragraph parsers plus the processing-instruction block parser, so a <?include ... ?> block is a ProcessingInstruction node rather than a raw HTML block. This is the one parser configuration in the tree; the linter, sync-docs, and every other parse path consume it (directly or via internal/lint's forwards) so parsing decisions stay consistent across surfaces.
func PIBlockParserPrioritized ¶
func PIBlockParserPrioritized() util.PrioritizedValue
PIBlockParserPrioritized returns the PI parser with its priority for registration.
func ParseContext ¶
ParseContext parses src verbatim — no front-matter handling — with the canonical pooled parser, recording link-reference definitions and other parse state in ctx. The parser is borrowed for the duration of the Parse call only and returned immediately, so concurrent callers each hold a distinct instance. Most callers want Parse; this lower-level entry exists for callers that need the goldmark parser.Context (e.g. the linter file model reading link reference definitions).
func Splice ¶
Splice returns a new slice equal to body with every edit range removed, in a single left-to-right pass. Edits must be ascending and non-overlapping — the order an AST walk over a parsed Document naturally yields heading and processing-instruction spans, so a caller collecting spans in document order can pass them straight through.
This is mdsmith's producer: it is byte-exact span surgery on the original source, not an AST-to-Markdown re-render, so its output never fights `mdsmith fix` (which is itself edit-based). body is not mutated; a fresh slice is returned.
func StripFrontMatter ¶
StripFrontMatter removes YAML front matter delimited by "---\n" from the beginning of source. It returns the front matter block (including delimiters) and the remaining content. If no front matter is found, prefix is nil and content equals source.
The closing fence is recognised only at the start of a line: either as the first bytes after the opening fence (empty FM body) or preceded by a newline. A naive bytes.Index search would otherwise truncate the front matter early when a YAML block-scalar value legitimately contains the literal `---\n` sequence (e.g. a `notes: |` value whose body includes an em-dash row).
Types ¶
type Document ¶
type Document struct {
// FrontMatter is the raw front-matter prefix including its ---
// fences, or nil when the source has no front matter.
FrontMatter []byte
// Body is source with the FrontMatter prefix removed. AST indexes
// into these bytes; pass Body to Splice when editing.
Body []byte
// AST is the goldmark document node parsed from Body.
AST ast.Node
}
Document is the result of Parse: the YAML front matter split off the top of the source, the body it was split from, and the goldmark AST of that body built with mdsmith's canonical parser.
func Parse ¶
Parse splits YAML front matter off source and parses the remaining body with the canonical parser (CommonMark plus the <?...?> processing-instruction block). It never errors and never panics: empty, body-only, and front-matter-only inputs all yield a document node (with an empty body for the front-matter-only case).
type ProcessingInstruction ¶
type ProcessingInstruction struct {
ast.BaseBlock
ClosureLine text.Segment
Name string // directive name from <?name
}
ProcessingInstruction is a custom AST block node for processing-instruction blocks (<?name ... ?>). It replaces the default ast.HTMLBlock representation for this PI syntax in CommonMark/HTML.
func (*ProcessingInstruction) Dump ¶
func (n *ProcessingInstruction) Dump(source []byte, level int)
Dump implements ast.Node.
func (*ProcessingInstruction) HasClosure ¶
func (n *ProcessingInstruction) HasClosure() bool
HasClosure reports whether the PI was closed with ?>. Mirrors ast.HTMLBlock.
func (*ProcessingInstruction) IsRaw ¶
func (n *ProcessingInstruction) IsRaw() bool
IsRaw implements ast.Node. Processing instructions contain raw content.
func (*ProcessingInstruction) Kind ¶
func (n *ProcessingInstruction) Kind() ast.NodeKind
Kind implements ast.Node.
Source Files