goldmark-meta ¶

goldmark-meta is an extension for the goldmark
that allows you to define document metadata in YAML format.

Usage ¶

Installation ¶

go get github.com/yuin/goldmark-meta

Markdown syntax ¶

YAML metadata block is a leaf block that can not have any markdown element
as a child.

YAML metadata must start with a YAML metadata separator.
This separator must be at first line of the document.

A YAML metadata separator is a line that only - is repeated.

YAML metadata must end with a YAML metadata separator.

You can define objects as a 1st level item. At deeper level, you can define
any kind of YAML element.

Example:

---
Title: goldmark-meta
Summary: Add YAML metadata to the document
Tags:
    - markdown
    - goldmark
---

# Heading 1

Access the metadata ¶

 1import (
 2    "bytes"
 3    "fmt"
 4    "github.com/yuin/goldmark"
 5    "github.com/yuin/goldmark/extension"
 6    "github.com/yuin/goldmark/parser"
 7    "github.com/yuin/goldmark-meta"
 8)
 9
10func main() {
11    markdown := goldmark.New(
12        goldmark.WithExtensions(
13            meta.Meta,
14        ),
15    )
16    source := `---
17Title: goldmark-meta
18Summary: Add YAML metadata to the document
19Tags:
20    - markdown
21    - goldmark
22---
23
24# Hello goldmark-meta
25`
26
27    var buf bytes.Buffer
28    context := parser.NewContext()
29    if err := markdown.Convert([]byte(source), &buf, parser.WithContext(context)); err != nil {
30        panic(err)
31    }
32    metaData := meta.Get(context)
33    title := metaData["Title"]
34    fmt.Print(title)
35}

Or WithStoresInDocument option:

 1import (
 2    "bytes"
 3    "fmt"
 4    "github.com/yuin/goldmark"
 5    "github.com/yuin/goldmark/extension"
 6    "github.com/yuin/goldmark/parser"
 7    "github.com/yuin/goldmark-meta"
 8)
 9
10func main() {
11	markdown := goldmark.New(
12		goldmark.WithExtensions(
13			meta.New(
14				meta.WithStoresInDocument(),
15			),
16		),
17	)
18	source := `---
19Title: goldmark-meta
20Summary: Add YAML metadata to the document
21Tags:
22    - markdown
23    - goldmark
24---
25`
26
27	document := markdown.Parser().Parse(text.NewReader([]byte(source)))
28	metaData := document.OwnerDocument().Meta()
29	title := metaData["Title"]
30    fmt.Print(title)

Render the metadata as a table ¶

You need to add extension.TableHTMLRenderer or the Table extension to
render metadata as a table.

 1import (
 2    "bytes"
 3    "fmt"
 4    "github.com/yuin/goldmark"
 5    "github.com/yuin/goldmark/extension"
 6    "github.com/yuin/goldmark/parser"
 7    "github.com/yuin/goldmark/renderer"
 8    "github.com/yuin/goldmark/util"
 9    "github.com/yuin/goldmark-meta"
10)
11
12func main() {
13    markdown := goldmark.New(
14        goldmark.WithExtensions(
15            meta.New(meta.WithTable()),
16        ),
17        goldmark.WithRendererOptions(
18            renderer.WithNodeRenderers(
19                util.Prioritized(extension.NewTableHTMLRenderer(), 500),
20            ),
21        ),
22    )
23    // OR
24    // markdown := goldmark.New(
25    //     goldmark.WithExtensions(
26    //         meta.New(meta.WithTable()),
27    //         extension.Table,
28    //     ),
29    // )
30    source := `---
31Title: goldmark-meta
32Summary: Add YAML metadata to the document
33Tags:
34    - markdown
35    - goldmark
36---
37
38# Hello goldmark-meta
39`
40
41    var buf bytes.Buffer
42    if err := markdown.Convert([]byte(source), &buf); err != nil {
43        panic(err)
44    }
45    fmt.Print(buf.String())
46}

License ¶

MIT

Author ¶

Yusuke Inuzuka