README
¶
goldmark-hashtag
goldmark-hashtag is an extension for the goldmark Markdown parser
that adds support for tagging documents with #hashtags.
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/hashtag@latest
Usage
To use goldmark-hashtag, import the hashtag package.
import "go.abhg.dev/goldmark/hashtag"
Then include the hashtag.Extender in the list of extensions you build your
goldmark.Markdown with.
goldmark.New(
goldmark.WithExtensions(
&hashtag.Extender{},
),
// ...
).Convert(src, out)
This alone has little effect
besides adding <span class="hashtag">...</span>
around hashtags in your Markdown document.
You must supply a hashtag.Resolver to render hashtags as links.
Link resolution
Supply a hashtag.Resolver to the hashtag.Extender
to render hashtags as links:
goldmark.New(
goldmark.WithExtensions(
&hashtag.Extender{
Resolver: hashtagResolver,
},
),
// ...
).Convert(src, out)
Syntax
Hashtags must always begin with a "#". The characters that follow that depend on the variant you have chosen. goldmark-hashtag supports the following variants:
- Default: Hashtags must begin with a letter, and may contain letters,
numbers and any of the following symbols:
/_-. goldmark-hashtag uses this variant if you do not specify one. - Obsidian: Hashtags can begin with and contain letters, numbers, emoji, and
any of the following symbols:
/_-, but must not contain only numbers.
You can specify the variant by setting the Variant property of the
hashtag.Extender.
&hashtag.Extender{
// ...
Variant: hashtag.ObsidianVariant,
}
Inspection
To collect all hashtags from a Markdown document, use Goldmark's ast.Walk
function after parsing the document.
For example, the following will populate the hashtags map with all hashtags
found in the document.
markdown := goldmark.New(
goldmark.WithExtensions(
&hashtag.Extender{
Resolver: hashtagResolver,
},
),
// ...
)
// Parse the Markdown document.
doc := markdown.Parser().Parse(text.NewReader(src))
// List the tags.
hashtags := make(map[string]struct{})
ast.Walk(doc, func(node ast.Node, enter bool) (ast.WalkStatus, error) {
if n, ok := node.(*hashtag.Node); ok && enter {
hashtags[string(n.Tag)] = struct{}{}
}
return ast.WalkContinue, nil
})
Documentation
¶
Overview ¶
Package hashtag provides support for #tag-style tags for the Goldmark Markdown parser.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Kind = ast.NewNodeKind("Hashtag")
Kind is the kind of hashtag AST nodes.
Functions ¶
This section is empty.
Types ¶
type Extender ¶
type Extender struct {
// Resolver specifies destination links for hashtags, if any.
//
// Defaults to no links.
Resolver Resolver
// Variant is the flavor of the hashtag syntax to support.
//
// Defaults to DefaultVariant. See the documentation of individual
// variants for more information.
Variant Variant
}
Extender extends a goldmark Markdown object with support for parsing and rendering hashtags.
Install it on your Markdown object upon creation.
goldmark.New(
goldmark.WithExtensions(
// ...
&hashtag.Extender{...},
),
// ...
)
Provide a Resolver to render tags as links that point to a specific destination.
type Node ¶
type Node struct {
ast.BaseInline
// Tag is the portion of the hashtag following the '#'.
Tag []byte
}
Node is a hashtag node in a Goldmark Markdown document.
type Parser ¶
type Parser struct {
// Variant is the flavor of the hashtag syntax to support.
//
// Defaults to DefaultVariant. See the documentation of individual
// variants for more information.
Variant Variant
}
Parser is a Goldmark inline parser for parsing hashtag nodes.
Hashtags start with "#". The list of other characters allowed in the hashtag is determined by variant. See the documentation for Variant for more details.
type Renderer ¶
type Renderer struct {
// Resolver specifies how where hashtag links should point, if at all.
//
// When a Resolver returns an empty destination for a hashtag, the
// Renderer will render the hashtag as plain text rather than a link.
//
// Defaults to empty destinations for all hashtags.
Resolver Resolver
// contains filtered or unexported fields
}
Renderer renders hashtag nodes into HTML, optionally linking them to specific pages.
#foo
Renders as the following by default.
<span class="hashtag">#foo</span>
Supply a Resolver that returns a non-empty destination to render it like the following.
<span class="hashtag"><a href="...">#foo</a></span>
func (*Renderer) RegisterFuncs ¶
func (r *Renderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)
RegisterFuncs registers rendering functions from this renderer onto the provided registerer.
type Resolver ¶
type Resolver interface {
// ResolveHashtag reports the link that the provided hashtag Node
// should point to, or an empty destination for hashtags that should
// not link to anything.
ResolveHashtag(*Node) (destination []byte, err error)
}
Resolver resolves hashtags to pages they should link to.
type Variant ¶
type Variant uint
Variant represents one of the different flavours of hashtag syntax.
const ( // DefaultVariant is the default flavor of hashtag syntax supported by // this package. // // In this format, hashtags start with "#" and an alphabet, followed by // zero or more alphanumeric characters and the following symbols. // // /_- DefaultVariant Variant = iota // ObsidianVariant is a flavor of the hashtag syntax that aims to be // compatible with Obsidian (https://obsidian.md/). // // In this format, hashtags start with "#" followed by alphabets, // numbers, emoji, or any of the following symbols. // // /_- // // Hashtags cannot be entirely numeric and must contain at least one // non-numeric character. // // See also https://help.obsidian.md/How+to/Working+with+tags. ObsidianVariant )
Source Files