README
¶
wlmarkdown
The leading implementation of the WikiLayer markdown dialect. It adds callouts,
map embeds, and page: and block: links to goldmark's GitHub-flavoured Markdown.
The Swift and Kotlin ports consume the same rules and test corpora.
Install the package:
go get github.com/wikilayer/wlmarkdown@v0.7.1
Recognise structured constructs or extract reader-visible text:
dialect := wlmarkdown.New()
found := dialect.Recognise([]byte("> [!TIP]\n> Try the shorter form.\n"))
plain := wlmarkdown.Strip([]byte("Read **this** before `make test`."))
Recognise returns a flat list in document order. Each Found describes a
callout, map, unreadable map, or link. Strip removes markdown syntax for search,
previews, and indexing while keeping code searchable.
What it recognises
A blockquote whose first line is exactly [!NOTE], [!TIP], [!IMPORTANT],
[!WARNING], or [!CAUTION] is a callout. A marker sharing its line with words or
written in another case leaves an ordinary quote.
A [!MAP] marker followed by a line of two numbers is a map embed. The remaining
lines of that paragraph are its caption. Coordinates contain digits with an
optional sign and fraction; their spelling is preserved. A latitude may go as far
as 90 and a longitude as far as 180. A pair outside those bounds becomes an
Unreadable node carrying the words the author wrote.
A written link may name a node under the page: or block: scheme. The dialect
reports the destination but does not resolve it against a store. Bare URLs are
linkified by GFM but, like angle-bracket autolinks, are omitted from Found.
Read Markers, Classes, and Schemes instead of copying their current values
into an application. DeclinedIn reports marked quotes the dialect left unchanged
when the parse uses a parser.Context:
pc := parser.NewContext()
p := wlmarkdown.New().Parser()
p.Parse(text.NewReader(source), parser.WithContext(pc))
declined := wlmarkdown.DeclinedIn(pc)
Rendering with goldmark
The library recognises constructs but does not render, decorate, or resolve them.
Build a goldmark instance from its extensions and register a renderer for every
kind returned by Kinds:
md := goldmark.New(
goldmark.WithExtensions(wlmarkdown.New().Extensions()...),
goldmark.WithRendererOptions(renderer.WithNodeRenderers(
util.Prioritized(yourCalloutRenderer{}, 500),
util.Prioritized(yourMapRenderer{}, 500),
util.Prioritized(yourUnreadableRenderer{}, 500),
)),
)
A goldmark converter without those renderers panics when it reaches a custom node. An application may instead replace the nodes in its own AST transformer. Every transformer in this package runs below priority 200, so a transformer registered at 200 or above sees all dialect nodes.
Nesting
A callout inside another callout remains part of the outer callout. A map directly inside a callout is still recognised, and links inside callouts are reported. These priorities are part of the shared corpus rather than renderer policy.
The corpus
corpus/rules.yaml defines the dialect's markers, coordinate alphabet, blanks, and
link schemes. corpus/dialect.yaml defines structured recognition, and
corpus/plain_text.yaml defines Strip and the ports' plain-text functions. New
rules and cases are added here first; every port runs copies of all three.
Bare-URL linking lies outside what the flat corpus can observe. Goldmark and the Kotlin port enable it; swift-markdown offers no equivalent option.
Documentation
The public API is published in the Go Reference.
Development
make test-build # compile the package and tests
make test # run the shared corpus and wiring tests
make lint # commentcensor, go vet, gofmt, and staticcheck
make build # all checks and the package build
Releases are published by the repository's Release workflow, after it repeats the complete build.
Lines of Code
Documentation
¶
Overview ¶
Package wlmarkdown recognises the WikiLayer markdown dialect with goldmark.
New provides the parser extensions and Recognise returns structured dialect constructs. Strip extracts reader-visible text for search and previews.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var KindCallout = ast.NewNodeKind("wlmarkdown.Callout")
KindCallout identifies a transformed callout node.
var KindMapEmbed = ast.NewNodeKind("wlmarkdown.MapEmbed")
KindMapEmbed identifies a transformed map embed node.
var KindUnreadable = ast.NewNodeKind("wlmarkdown.Unreadable")
KindUnreadable identifies a map whose coordinates lie outside the Earth.
Functions ¶
Types ¶
type Callout ¶
Callout is a blockquote transformed from a recognised callout marker. Class is the value assigned to that marker by the bundled rules.
type Declined ¶
type Declined struct {
Marker string
}
Declined records a dialect marker from a quote left unchanged. Marker keeps the spelling used by the dialect.
func DeclinedIn ¶
DeclinedIn returns marked quotes the dialect declined during a parse.
type Dialect ¶
type Dialect struct {
// contains filtered or unexported fields
}
Dialect holds the rules and goldmark extensions of the WikiLayer dialect.
func (Dialect) Classes ¶
Classes returns every callout class the dialect can report, in sorted order.
func (Dialect) Extensions ¶
Extensions returns the GFM and WikiLayer goldmark extensions in parse order.
func (Dialect) Markers ¶
Markers returns every marker that can open a dialect construct, in sorted order.
type Found ¶
type Found struct {
Kind string `yaml:"kind"`
Class string `yaml:"class,omitempty"`
Lat string `yaml:"lat,omitempty"`
Lng string `yaml:"lng,omitempty"`
Caption string `yaml:"caption,omitempty"`
Scheme string `yaml:"scheme,omitempty"`
Destination string `yaml:"destination,omitempty"`
Text string `yaml:"text,omitempty"`
}
Found is one dialect construct found in a document. Kind selects the meaningful fields: Class and Text for callout, Lat, Lng, and Caption for map, Text for unreadable, or Scheme, Destination, and Text for link.
type MapEmbed ¶
MapEmbed is a blockquote transformed from a valid map marker and point. Lat and Lng preserve the coordinate spelling, and Caption preserves its markdown.
type Unreadable ¶
Unreadable preserves the contents of a map that cannot be placed.
func (*Unreadable) Dump ¶
func (n *Unreadable) Dump(source []byte, level int)
Dump writes the node in goldmark's diagnostic tree format.
Source Files