frontmatter

Documentation

Overview

Package frontmatter adds support for parsing front matter in Markdown documents.

It supports YAML front matter out of the box, and can be extended to support other formats.

Index

• Variables
• type Data
  • func Get(ctx parser.Context) *Data
  • func (d *Data) Decode(dst any) error
• type Extender
  • func (e *Extender) Extend(md goldmark.Markdown)
• type Format
• type MetaTransformer
  • func (t *MetaTransformer) Transform(node *ast.Document, _ text.Reader, pc parser.Context)
• type Mode
  • func (i Mode) String() string
• 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{YAML}

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

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 Extender

type Extender struct {
	// Mode specifies the mode in which the extender operates.
	// See documentation of the Mode type for more information.
	Mode Mode
}

Extender adds support for front matter to a Goldmark Markdown parser.

Use it by installing it into the goldmark.Markdown object upon creation. For example:

goldmark.New(
	// ...
	goldmark.WithExtensions(
		// ...
		&frontmatter.Extender{},
	),
)

func (*Extender) Extend

func (e *Extender) Extend(md goldmark.Markdown)

Extend extends the provided Goldmark Markdown.

type Format

type Format struct {

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

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

	Delim byte
}

Format defines a front matter format recognized by this package.

type MetaTransformer

type MetaTransformer struct{}

MetaTransformer is an AST transformer that converts the front matter of a document into a map[string]interface{} and stores it on the document as metadata.

Access the metadata by calling the ast.Document.Meta method.

func (*MetaTransformer) Transform

func (t *MetaTransformer) Transform(node *ast.Document, _ text.Reader, pc parser.Context)

Transform fetches the front matter from the parser context and sets it as the metadata of the document.

This is a no-op if the front matter is not present in the context or it cannot be decoded.

type Mode

type Mode int

Mode specifies the mode in which the Extender operates. By default, the extender extracts the front matter from the document, but does not render it or do anything else with it.

Change the mode by setting the Mode field of the Extender object.

const (
	// SetMetadata instructs the extender to convert the front matter
	// into a map[string]interface{} and set it as the metadata
	// of the document.
	//
	// This may be accessed by calling the Document.Meta() method.
	SetMetadata Mode = 1 << iota
)

func (Mode) String

func (i Mode) String() string

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.