README
¶
goldmark-wikilink
goldmark-wikilink is an extension for the goldmark Markdown parser that
supports parsing [[...]]-style wiki links
and ![[...]]-style embedded wiki links.
Demo: A web-based demonstration of the extension is available at https://abhinav.github.io/goldmark-hashtag/demo/.
Installation
go get go.abhg.dev/goldmark/wikilink@latest
Usage
To use goldmark-wikilink, import the wikilink package.
import "go.abhg.dev/goldmark/wikilink"
Then include the wiklink.Extender in the list of extensions
that you build your goldmark.Markdown with.
goldmark.New(
goldmark.WithExtensions(
&wiklink.Extender{},
),
// ...
)
Link resolution
By default, wikilinks will be converted to URLs based on the page name, unless they already have an extension.
[[Foo]] => "Foo.html"
[[Foo bar]] => "Foo bar.html"
[[Foo.pdf]] => "Foo.pdf"
[[Foo.png]] => "Foo.png"
You can change this by supplying a custom wikilink.Resolver
to your wikilink.Extender when you install it.
goldmark.New(
goldmark.WithExtensions(
// ...
&wiklink.Extender{
Resolver: myresolver,
},
),
// ...
)
Embedding images
Use the embedded link form (![[...]]) to add images to a document.
![[foo.png]]
Add alt text to images with the ![[...|...]] form:
![[foo.png|alt text]]
Documentation
¶
Overview ¶
Package wikilink provides support for parsing [[...]]-style and ![[...]]-style wiki links to the goldmark Markdown parser.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Kind = ast.NewNodeKind("WikiLink")
Kind is the kind of the wikilink AST node.
Functions ¶
This section is empty.
Types ¶
type Extender ¶
type Extender struct {
// Resoler specifies how to resolve destinations for linked pages.
//
// Uses DefaultResolver if unspecified.
Resolver Resolver
}
Extender extends a goldmark Markdown object with support for parsing and rendering Wikilinks.
type Node ¶
type Node struct {
ast.BaseInline
// Page to which this wikilink points.
//
// This may be blank for links to headers within the same document
// like [[#Foo]].
Target []byte
// Fragment portion of the link, if any.
//
// For links in the form, [[Foo bar#Baz qux]], this is the portion
// after the "#".
Fragment []byte
// Whether this link starts with a bang (!).
//
// ![[foo.png]]
//
// This indicates that the resource should be embedded (e.g. images).
Embed bool
}
Node is a Wikilink AST node. Wikilinks have two components: the target and the label.
The target is the page to which this link points, and the label is the text that displays for this link.
For links in the following form, the label and the target are the same.
[[Foo bar]]
For links in the following form, the target is the portion of the link to the left of the "|", and the label is the portion to the right.
[[Foo bar|baz qux]]
type Parser ¶
type Parser struct{}
Parser parses wikilinks.
Install it on your goldmark Markdown object with Extender, or install it directly on your goldmark Parser by using the WithInlineParsers option.
wikilinkParser := util.Prioritized(&wikilink.Parser{...}, 199)
goldmarkParser.AddOptions(parser.WithInlineParsers(wikilinkParser))
Note that the priority for the wikilink parser must 199 or lower to take precedence over the plain Markdown link parser which has a priority of 200.
func (*Parser) Parse ¶
Parse parses a wikilink in one of the following forms:
[[...]] (simple) ![[...]] (embedded)
Both, simple and embedded wikilinks support the following syntax:
[[target]] [[target|label]]
If the label is omitted, the target is used as the label.
The target may optionally contain a fragment identifier:
[[target#fragment]]
type Renderer ¶
type Renderer struct {
// Resolver determines destinations for wikilink pages.
//
// If a Resolver returns an empty destination, the Renderer will skip
// the link and render just its contents. That is, instead of,
//
// <a href="foo">bar</a>
//
// The renderer will render just the following.
//
// bar
//
// Defaults to DefaultResolver if unspecified.
Resolver Resolver
// contains filtered or unexported fields
}
Renderer renders wikilinks as HTML.
Install it on your goldmark Markdown object with Extender, or directly on a goldmark Renderer by using the WithNodeRenderers option.
wikilinkRenderer := util.Prioritized(&wikilink.Renderer{...}, 199)
goldmarkRenderer.AddOptions(renderer.WithNodeRenderers(wikilinkRenderer))
func (*Renderer) RegisterFuncs ¶
func (r *Renderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)
RegisterFuncs registers wikilink rendering functions with the provided goldmark registerer. This teaches goldmark to call us when it encounters a wikilink in the AST.
func (*Renderer) Render ¶
func (r *Renderer) Render(w util.BufWriter, src []byte, node ast.Node, entering bool) (ast.WalkStatus, error)
Render renders the provided Node. It must be a Wikilink Node.
goldmark will call this method if this renderer was registered with it using the WithNodeRenderers option.
All nodes will be rendered as links (with <a> tags), except for embed links (![[..]]) that refer to images. Those will be rendered as images (with <img> tags).
type Resolver ¶
type Resolver interface {
// ResolveWikilink returns the address of the page that the provided
// wikilink points to. The destination will be URL-escaped before
// being placed into a link.
//
// If ResolveWikilink returns a non-nil error, rendering will be
// halted.
//
// If ResolveWikilink returns a nil destination and error, the
// Renderer will omit the link and render its contents as a regular
// string.
ResolveWikilink(*Node) (destination []byte, err error)
}
Resolver resolves pages referenced by wikilinks to their destinations.
var DefaultResolver Resolver = defaultResolver{}
DefaultResolver is a minimal wiklink resolver that resolves wikilinks relative to the source page.
It adds ".html" to the end of the target if the target does not have an extension.
For example,
[[Foo]] // => "Foo.html" [[Foo bar]] // => "Foo bar.html" [[foo/Bar]] // => "foo/Bar.html" [[foo.pdf]] // => "foo.pdf" [[foo.png]] // => "foo.png"
Source Files