meta

README

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

import (
    "bytes"
    "fmt"
    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/extension"
    "github.com/yuin/goldmark/parser"
    "github.com/yuin/goldmark-meta"
)

func main() {
    markdown := goldmark.New(
        goldmark.WithExtensions(
            meta.Meta,
        ),
    )
    source := `---
Title: goldmark-meta
Summary: Add YAML metadata to the document
Tags:
    - markdown
    - goldmark
---

# Hello goldmark-meta
`

    var buf bytes.Buffer
    context := parser.NewContext()
    if err := markdown.Convert([]byte(source), &buf, parser.WithContext(context)); err != nil {
        panic(err)
    }
    metaData := meta.Get(context)
    title := metaData["Title"]
    fmt.Print(title)
}

Or WithStoresInDocument option:

import (
    "bytes"
    "fmt"
    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/extension"
    "github.com/yuin/goldmark/parser"
    "github.com/yuin/goldmark/text"
    "github.com/yuin/goldmark-meta"
)

func main() {
	markdown := goldmark.New(
		goldmark.WithExtensions(
			meta.New(
				meta.WithStoresInDocument(),
			),
		),
	)
	source := `---
Title: goldmark-meta
Summary: Add YAML metadata to the document
Tags:
    - markdown
    - goldmark
---
`

	document := markdown.Parser().Parse(text.NewReader([]byte(source)))
	metaData := document.OwnerDocument().Meta()
	title := metaData["Title"]
	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.

import (
    "bytes"
    "fmt"
    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/extension"
    "github.com/yuin/goldmark/parser"
    "github.com/yuin/goldmark/renderer"
    "github.com/yuin/goldmark/util"
    "github.com/yuin/goldmark-meta"
)

func main() {
    markdown := goldmark.New(
        goldmark.WithExtensions(
            meta.New(meta.WithTable()),
        ),
        goldmark.WithRendererOptions(
            renderer.WithNodeRenderers(
                util.Prioritized(extension.NewTableHTMLRenderer(), 500),
            ),
        ),
    )
    // OR
    // markdown := goldmark.New(
    //     goldmark.WithExtensions(
    //         meta.New(meta.WithTable()),
    //         extension.Table,
    //     ),
    // )
    source := `---
Title: goldmark-meta
Summary: Add YAML metadata to the document
Tags:
    - markdown
    - goldmark
---

# Hello goldmark-meta
`

    var buf bytes.Buffer
    if err := markdown.Convert([]byte(source), &buf); err != nil {
        panic(err)
    }
    fmt.Print(buf.String())
}

License

MIT

Author

Yusuke Inuzuka

Documentation

Overview

package meta is a extension for the goldmark(http://github.com/yuin/goldmark).

This extension parses YAML metadata blocks and store metadata to a parser.Context.

Index

• Variables
• func Get(pc parser.Context) map[string]interface{}
• func GetItems(pc parser.Context) yaml.MapSlice
• func New(opts ...Option) goldmark.Extender
• func NewParser() parser.BlockParser
• func TryGet(pc parser.Context) (map[string]interface{}, error)
• func TryGetItems(pc parser.Context) (yaml.MapSlice, error)
• func Unmarshal(pc parser.Context, out interface{}) error
• type Option
  • func WithStoresInDocument() Option
  • func WithTable() Option

Variables

var (
	ContextKeyNotExist      = errors.New("context key not exist")
	ContextDataAssertFailed = errors.New("context data assert failed")
)

var Meta = &meta{}

Meta is a extension for the goldmark.

Functions

func Get

func Get(pc parser.Context) map[string]interface{}

Get returns a YAML metadata.

func GetItems

func GetItems(pc parser.Context) yaml.MapSlice

GetItems returns a YAML metadata. GetItems preserves defined key order.

func New

func New(opts ...Option) goldmark.Extender

New returns a new Meta extension.

func NewParser

func NewParser() parser.BlockParser

NewParser returns a BlockParser that can parse YAML metadata blocks.

func TryGet

func TryGet(pc parser.Context) (map[string]interface{}, error)

TryGet tries to get a YAML metadata. If there are YAML parsing errors, then nil and error are returned

func TryGetItems

func TryGetItems(pc parser.Context) (yaml.MapSlice, error)

TryGetItems returns a YAML metadata. TryGetItems preserves defined key order. If there are YAML parsing errors, then nil and erro are returned.

func Unmarshal

func Unmarshal(pc parser.Context, out interface{}) error

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option interface sets options for this extension.

func WithStoresInDocument

func WithStoresInDocument() Option

WithStoresInDocument is a functional option that parser will store YAML meta in ast.Document.Meta().

func WithTable

func WithTable() Option

WithTable is a functional option that renders a YAML metadata as a table.