goldmark-mmd

A different way of handling Markdown Metadata
git clone git://src.gearsix.net/goldmark-mmd
Log | Files | Refs | Atom | README | LICENSE

README.md (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 = `:`&emsp;(`<!--:...:-->`)
     41 - TOML = `#`&emsp;(`<!--#...#-->`)
     42 - JSON = `{}`&emsp;(`<!--{...}-->`)
     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