1goldmark-meta
2=========================
3[![GoDev][godev-image]][godev-url]
4
5[godev-image]: https://pkg.go.dev/badge/github.com/yuin/goldmark-meta
6[godev-url]: https://pkg.go.dev/github.com/yuin/goldmark-meta
7
8
9goldmark-meta is an extension for the [goldmark](http://github.com/yuin/goldmark)
10that allows you to define document metadata in YAML format.
11
12Usage
13--------------------
14
15### Installation
16
17```
18go get github.com/yuin/goldmark-meta
19```
20
21### Markdown syntax
22
23YAML metadata block is a leaf block that can not have any markdown element
24as a child.
25
26YAML metadata must start with a **YAML metadata separator**.
27This separator must be at first line of the document.
28
29A **YAML metadata separator** is a line that only `-` is repeated.
30
31YAML metadata must end with a **YAML metadata separator**.
32
33You can define objects as a 1st level item. At deeper level, you can define
34any kind of YAML element.
35
36Example:
37
38```
39---
40Title: goldmark-meta
41Summary: Add YAML metadata to the document
42Tags:
43 - markdown
44 - goldmark
45---
46
47# Heading 1
48```
49
50
51### Access the metadata
52
53```go
54import (
55 "bytes"
56 "fmt"
57 "github.com/yuin/goldmark"
58 "github.com/yuin/goldmark/extension"
59 "github.com/yuin/goldmark/parser"
60 "github.com/yuin/goldmark-meta"
61)
62
63func main() {
64 markdown := goldmark.New(
65 goldmark.WithExtensions(
66 meta.Meta,
67 ),
68 )
69 source := `---
70Title: goldmark-meta
71Summary: Add YAML metadata to the document
72Tags:
73 - markdown
74 - goldmark
75---
76
77# Hello goldmark-meta
78`
79
80 var buf bytes.Buffer
81 context := parser.NewContext()
82 if err := markdown.Convert([]byte(source), &buf, parser.WithContext(context)); err != nil {
83 panic(err)
84 }
85 metaData := meta.Get(context)
86 title := metaData["Title"]
87 fmt.Print(title)
88}
89```
90
91Or `WithStoresInDocument` option:
92
93```go
94import (
95 "bytes"
96 "fmt"
97 "github.com/yuin/goldmark"
98 "github.com/yuin/goldmark/extension"
99 "github.com/yuin/goldmark/parser"
100 "github.com/yuin/goldmark-meta"
101)
102
103func main() {
104 markdown := goldmark.New(
105 goldmark.WithExtensions(
106 meta.New(
107 meta.WithStoresInDocument(),
108 ),
109 ),
110 )
111 source := `---
112Title: goldmark-meta
113Summary: Add YAML metadata to the document
114Tags:
115 - markdown
116 - goldmark
117---
118`
119
120 document := markdown.Parser().Parse(text.NewReader([]byte(source)))
121 metaData := document.OwnerDocument().Meta()
122 title := metaData["Title"]
123 fmt.Print(title)
124```
125
126### Render the metadata as a table
127
128You need to add `extension.TableHTMLRenderer` or the `Table` extension to
129render metadata as a table.
130
131```go
132import (
133 "bytes"
134 "fmt"
135 "github.com/yuin/goldmark"
136 "github.com/yuin/goldmark/extension"
137 "github.com/yuin/goldmark/parser"
138 "github.com/yuin/goldmark/renderer"
139 "github.com/yuin/goldmark/util"
140 "github.com/yuin/goldmark-meta"
141)
142
143func main() {
144 markdown := goldmark.New(
145 goldmark.WithExtensions(
146 meta.New(meta.WithTable()),
147 ),
148 goldmark.WithRendererOptions(
149 renderer.WithNodeRenderers(
150 util.Prioritized(extension.NewTableHTMLRenderer(), 500),
151 ),
152 ),
153 )
154 // OR
155 // markdown := goldmark.New(
156 // goldmark.WithExtensions(
157 // meta.New(meta.WithTable()),
158 // extension.Table,
159 // ),
160 // )
161 source := `---
162Title: goldmark-meta
163Summary: Add YAML metadata to the document
164Tags:
165 - markdown
166 - goldmark
167---
168
169# Hello goldmark-meta
170`
171
172 var buf bytes.Buffer
173 if err := markdown.Convert([]byte(source), &buf); err != nil {
174 panic(err)
175 }
176 fmt.Print(buf.String())
177}
178```
179
180
181License
182--------------------
183MIT
184
185Author
186--------------------
187Yusuke Inuzuka