package anchor

import "go.abhg.dev/goldmark/anchor"

Package anchor is an extension for the Goldmark Markdown parser adding support for anchors for all headers.

Index

Variables

var Kind = ast.NewNodeKind("Anchor")

Kind is the NodeKind used by anchor nodes.

Types

type Attributer

type Attributer interface {
	// AnchorAttributes returns the attributes
	// that should be attached to the anchor node
	// for the given header.
	//
	// If AnchorAttributes returns an empty map or nil,
	// no attributes will be added.
	AnchorAttributes(*HeaderInfo) map[string]string
}

Attributer determines attributes that will be attached to an anchor node.

By default, we will add 'class="anchor"' to all nodes.

type Attributes

type Attributes map[string]string

Attributes is an Attributer that uses a constant set of attributes for all anchor nodes.

Pass this into Extender or Transformer to specify custom attributes. 

anchor.Extender{
	Attributer: Attributes{"class": "permalink"},
}

func (Attributes) AnchorAttributes

func (as Attributes) AnchorAttributes(*HeaderInfo) map[string]string

AnchorAttributes reports the attributes associated with this object for all headers.

type Extender

type Extender struct {
	// Texter determines the anchor text.
	//
	// Defaults to '¶' if unspecified.
	Texter Texter

	// Position specifies where the anchor will be placed in a header.
	//
	// Defaults to After.
	Position Position

	// Attributer determines the attributes
	// that will be associated with the anchor link.
	//
	// Defaults to adding a 'class="anchor"' attribute.
	Attributer Attributer
}

Extender adds support for anchors to a Goldmark Markdown parser.

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

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

func (*Extender) Extend

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

Extend extends the provided Goldmark Markdown.

type HeaderInfo

type HeaderInfo struct {
	// Level of the header.
	Level int

	// Identifier for the header on the page.
	// This will typically become part of the URL fragment.
	ID []byte
}

HeaderInfo holds information about a header for which an anchor is being considered.

type Node

type Node struct {
	ast.BaseInline

	// ID of the header this anchor is for.
	ID []byte

	// Level of the header that this anchor is for.
	Level int

	// Value is the text inside the anchor.
	// Typically this is a fixed string
	// like '¶' or '#'.
	Value []byte
}

Node is an anchor node in the Markdown AST.

func (*Node) Dump

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

Dump dumps this node to stdout for debugging.

func (*Node) Kind

func (*Node) Kind() ast.NodeKind

Kind reports that this is a Anchor node.

type Position

type Position int

Position specifies where inside a heading we should place an anchor Node. 

const (
	// After places the anchor node after the heading text.
	//
	// This is the default.
	After Position = iota

	// Before places the anchor node before the heading text.
	Before
)

func (Position) String

func (i Position) String() string

type Renderer

type Renderer struct {
	// Position specifies where in the header text
	// the anchor is being added.
	Position Position
}

Renderer renders anchor [Node]s.

func (*Renderer) RegisterFuncs

func (r *Renderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer)

RegisterFuncs registers functions against the provided goldmark Registerer.

func (*Renderer) RenderNode

func (r *Renderer) RenderNode(w util.BufWriter, src []byte, node ast.Node, entering bool) (ast.WalkStatus, error)

RenderNode renders an anchor node. Goldmark will invoke this method when it encounters a Node.

type Texter

type Texter interface {
	// AnchorText returns the anchor text
	// that should be used for the provided header info.
	//
	// If AnchorText returns an empty slice or nil,
	// an anchor will not be generated for this header.
	AnchorText(*HeaderInfo) []byte
}

Texter determines the anchor text.

This is the clickable text displayed next to the header which tells readers that they can use it as an anchor to the header.

By default, we will use the string '¶'.

func Text

func Text(s string) Texter

Text builds a Texter that uses a constant string as the anchor text.

Pass this into Extender or Transformer to specify a custom anchor text. 

anchor.Extender{
	Texter: Text("#"),
}

type Transformer

type Transformer struct {
	// Texter determines the anchor text.
	//
	// Defaults to '¶' for all headers if unset.
	Texter Texter

	// Position specifies where the anchor will be placed in a header.
	//
	// Defaults to After.
	Position Position

	// Attributer determines the attributes
	// that will be associated with the anchor link.
	//
	// Defaults to adding a 'class="anchor"' attribute
	// for all headers if unset.
	Attributer Attributer
}

Transformer transforms a Goldmark Markdown AST, adding anchor Node objects for headers across the document.

func (*Transformer) Transform

func (t *Transformer) Transform(doc *ast.Document, reader text.Reader, pctx parser.Context)

Transform traverses and transforms the provided Markdown document.

This method is typically called by Goldmark and should not need to be invoked directly.