README.md (raw) (3645B)
1 --- 2 Problem: In some parsers this will be rendered. 3 Solution: mmd 4 --- 5 6 mmd 7 === 8 9 *Fork of the [goldmark-meta](http://github.com/yuin/goldmark-meta) extension for [goldmark](http://github.com/yuin/goldmark), both by [yuin](http://github.com/yuin).* 10 11 This extension provides parsing of metadata in markdown using a different syntax than most to avoid the metadata being improperly parsed by any markdown renderer that doesn't parse for metadata. 12 13 Motivation 14 ---------- 15 16 Most extensions for markdown that provide parsing for document metadata use YAML with its [Document Markers](https://yaml.org/spec/1.2.2/#912-document-markers) syntax. 17 This is the idiomatic way of parsing metadata for in a markdown document, since [jekyll](https://jekyllrb.com/docs/front-matter/) started using it. 18 19 [Hugo](gohugo.io) (a tool similair to jekyll) later decided it would allow for multiple data formats, which required different document markers for those languages. 20 For JSON the marker was simply the opening `{` and for TOML it was `+++`. 21 22 The are great solutions but all of them also render in any markdown parser (e.g. GitHub) that doesn't expect metadata, causing an awkward section at the top of the render (see the top of this document). 23 24 To deal with this, the original *goldmark-meta* extension added a bunch of code that gave the option to render metdata as a HTML table but my argument is that metadata shouldn't be rendered at all. 25 26 This extension uses a different syntax to avoid the issue by putting the metadata in a HTML comment, that way it doesn't get rendered regardless of the markdown parser - which is how metadata should be treated. 27 28 29 Syntax 30 ------ 31 32 Metadata must start of the buffer using an **opening HTML comment tag** (`<!--`), followed by a **signal character** (signalling the metadata format being used). 33 34 Metadata must end with the same **signal character** followed by **closing HTML comment tag** (`-->`). 35 36 Everything inbetween these two tags should be the metadata in the signalled syntax. 37 38 ### Signal Characters 39 40 - YAML = `:` (`<!--:...:-->`) 41 - TOML = `#` (`<!--#...#-->`) 42 - JSON = `{}` (`<!--{...}-->`) 43 44 45 Usage 46 ----- 47 48 This is an extension to [goldmark](http://github.com/yuin/goldmark), so it'll need to be used in conjuction with it. 49 50 ### Installation 51 52 ``` 53 go get github.com/gearsix/mmd 54 ``` 55 56 57 ### Access the metadata 58 59 ```go 60 import ( 61 "bytes" 62 "fmt" 63 64 "github.com/yuin/goldmark" 65 "github.com/yuin/goldmark/parser" 66 "github.com/gearsix/mmd" 67 ) 68 69 func main() { 70 markdown := goldmark.New(goldmark.WithExtensions(mmd.MarkdownMeta)) 71 source := `<!--: 72 Title: Markdown Meta 73 Tags: 74 - markdown 75 - goldmark 76 :--> 77 78 This is an example of markdown meta using YAML. 79 ` 80 81 var buf bytes.Buffer 82 context := parser.NewContext() 83 if err := markdown.Convert([]byte(source), &buf, parser.WithContext(context)); err != nil { 84 panic(err) 85 } 86 metaData := mmd.Get(context) 87 title := metaData["Title"] 88 fmt.Print(title) 89 } 90 ``` 91 92 Or `WithStoresInDocument` option: 93 94 ```go 95 import ( 96 "bytes" 97 "fmt" 98 "github.com/yuin/goldmark" 99 "github.com/yuin/goldmark/extension" 100 "github.com/yuin/goldmark/parser" 101 "github.com/yuin/goldmark/text" 102 "github.com/gearsix/mmd" 103 ) 104 105 func main() { 106 markdown := goldmark.New(goldmark.WithExtensions( 107 meta.New(mmd.WithStoresInDocument()), 108 )) 109 source := `<!--{ "Title": "Markdown Meta", "Tags": [ "markdown", "goldmark" ] }--> 110 This is an example of markdown meta using JSON. 111 ` 112 113 document := markdown.Parser().Parse(text.NewReader([]byte(source))) 114 metaData := document.OwnerDocument().MarkdownMeta() 115 title := metaData["Title"] 116 fmt.Print(title) 117 } 118 ``` 119 120 License 121 ------- 122 MIT 123 124 Authors 125 ------- 126 127 - Yusuke Inuzuka 128 - gearsix