frontmatter

README

Code vendored from https://github.com/abhinav/goldmark-frontmatter with minor modifications.

Documentation

Index

• Variables
• type Data
  • func Get(ctx parser.Context) *Data
  • func (d *Data) Decode(dst any) error
• type Format
• type Node
  • func (n *Node) Dump(source []byte, level int)
  • func (n *Node) Kind() ast.NodeKind
• type Parser
  • func (*Parser) CanAcceptIndentedLine() bool
  • func (*Parser) CanInterruptParagraph() bool
  • func (p *Parser) Close(node ast.Node, reader text.Reader, pc parser.Context)
  • func (p *Parser) Continue(node ast.Node, reader text.Reader, _ parser.Context) parser.State
  • func (p *Parser) Open(_ ast.Node, reader text.Reader, _ parser.Context) (ast.Node, parser.State)
  • func (p *Parser) Trigger() []byte

Variables

var DefaultFormats = []Format{TOML, YAML}

DefaultFormats is the list of frontmatter formats that are recognized by default.

var TOML = Format{
	Name:      "TOML",
	Delim:     '+',
	Unmarshal: toml.Unmarshal,
}

TOML provides support for frontmatter in the TOML format. Front matter in this format is expected to be delimited by three or more '+' characters.

+++
title = "Hello, world!"
tags = ["foo", "bar"]
+++

var YAML = Format{
	Name:      "YAML",
	Delim:     '-',
	Unmarshal: yaml.Unmarshal,
}

YAML provides support for frontmatter in the YAML format. Front matter in this format is expected to be delimited by three or more '-' characters.

---
title: Hello, world!
tags:
  - foo
  - bar
---

Types

type Data

type Data struct {
	// contains filtered or unexported fields
}

Data holds the front matter data. Use Get to retrieve the data from the parser.Context.

func Get

func Get(ctx parser.Context) *Data

Get retrieves the front matter data from the parser.Context. If the data is not present, it returns nil.

func (*Data) Decode

func (d *Data) Decode(dst any) error

Decode decodes the front matter data into the provided value. The value must be a pointer to a struct or a map.

data := frontmatter.Get(ctx)
if data == nil {
	return errors.New("no front matter")
}

var metadata struct {
	Title string
	Tags []string
}
if err := data.Decode(&metadata); err != nil {
	return err
}

type Format

type Format struct {
	// Name is a human-readable name for the format.
	//
	// It may be used in error messages.
	Name string

	// Delim specifies the delimiter that marks front matter
	// in this format.
	//
	// There must be at least three of these in a row
	// for the front matter to be recognized.
	Delim byte

	// Unmarshal unmarshals the front matter data into the provided value.
	Unmarshal func([]byte, any) error
}

Format defines a front matter format recognized by this package.

type Node

type Node struct {
	ast.BaseBlock

	// Format holds the front matter format we matched.
	Format Format

	// Number of times the delimiter was repeated
	// in the opening line.
	DelimCount int

	// Segment holds the text range over which the front matter spans.
	Segment text.Segment
}

Node stores information about the parse state before the front matter is placed in the parser context.

func (*Node) Dump

func (n *Node) Dump(source []byte, level int)

Dump implements Node.Dump.

func (*Node) Kind

func (n *Node) Kind() ast.NodeKind

Kind implements Node.Kind.

type Parser

type Parser struct {
	// Formats specifies the front matter formats
	// supported by the parser.
	//
	// If Formats is empty, DefaultFormats is used.
	Formats []Format
	// contains filtered or unexported fields
}

Parser parses front matter from a Markdown document.

func (*Parser) CanAcceptIndentedLine

func (*Parser) CanAcceptIndentedLine() bool

CanAcceptIndentedLine reports that a frontmatter block cannot be indented.

This implements parser.BlockParser.

func (*Parser) CanInterruptParagraph

func (*Parser) CanInterruptParagraph() bool

CanInterruptParagraph reports that a frontmatter block cannot interrupt a paragraph.

This implements parser.BlockParser.

func (*Parser) Close

func (p *Parser) Close(node ast.Node, reader text.Reader, pc parser.Context)

Close cleans up after parsing a frontmatter block.

This implements parser.BlockParser.

func (*Parser) Continue

func (p *Parser) Continue(node ast.Node, reader text.Reader, _ parser.Context) parser.State

Continue continues parsing the following lines of a frontmatter block, transitioning to Close when the block is finished.

This implements parser.BlockParser.

func (*Parser) Open

func (p *Parser) Open(_ ast.Node, reader text.Reader, _ parser.Context) (ast.Node, parser.State)

Open begins parsing a frontmatter block, returning nil if a frontmatter block is not found.

This implements parser.BlockParser.

func (*Parser) Trigger

func (p *Parser) Trigger() []byte

Trigger returns bytes that can trigger this parser.

This implements parser.BlockParser.