# README

goldmark-anchor

goldmark-anchor is an extension for the goldmark Markdown parser that adds support for anchors next to all headers.

Installation

go get go.abhg.dev/goldmark/anchor@latest

Usage

To use goldmark-anchor, import the anchor package.

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

Then include the anchor.Extender in the list of extensions when constructing your goldmark.Markdown.

goldmark.New(
  goldmark.WithParserOptions(
    parser.WithAutoHeadingID(), // read note
  ),
  goldmark.WithExtensions(
    // ...
    &anchor.Extender{},
  ),
).Convert(src, out)

This will begin adding '¶' anchors next to all headers in your Markdown files.

NOTE: The example above adds the parser.WithAutoHeadingID option. Without this, or a custom implementation of parser.IDs, Goldmark will not add id attributes to headers. If a header does not have an id, then goldmark-anchor will not generate an anchor for it.

Changing anchor text

Change the anchor text by setting the Texter field of the Extender to an anchor.Text value.

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

Dynamic anchor text

You can dynamically calculate anchor text by supplying a custom implementation of Texter to the Extender.

For example, the following Texter repeats '#' matching the header level, providing anchors similar to Markdown #-style headers.

type customTexter struct{}

func (*customTexter) AnchorText(h *anchor.HeaderInfo) []byte {
  return bytes.Repeat([]byte{'#'}, h.Level)
}

// Elsewhere:

&anchor.Extender{
  Texter: &customTexter{},
}

Skipping headers

To skip headers, supply a custom Texter that returns an empty output for the AnchorText method.

The following Texter will not render anchors for level 1 headers.

type customTexter struct{}

func (*customTexter) AnchorText(h *anchor.HeaderInfo) []byte {
  if h.Level == 1 {
    return nil
  }
  return []byte("#")
}

Changing anchor attributes

Change the anchor attributes by setting the Attributer field of the Extender.

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

By default, goldmark-anchor will add class="anchor" to all anchors. Set Attributer to anchor.Attributes{} to disable this.

&anchor.Extender{
  Attributer: anchor.Attributes{},
}

Changing anchor positioning

Anchors can appear either at the start of the header before the header text, or at the end after the header text.

<!-- Before -->
<h1><a href="#">#</a> Foo</h1>

<!-- After -->
<h1>Foo <a href="#">¶</a></h1>

You can choose the placement by setting the Position field of Extender.

&anchor.Extender{
  Position: anchor.Before, // or anchor.After
}

By default, goldmark-anchor will place anchors after the header text.

FAQ

Why are no anchors being generated?

By default, Goldmark does not generate IDs for headings. Since goldmark-anchor generates anchors only for headings with IDs, this can result in no anchors being generated

You must enable heading ID generation using one of the following methods:

set the parser.WithAutoHeadingID option
supply your own parser.IDs implementation

Alternatively, if your document specifies heading attributes manually, enable the parser.WithHeadingAttribute option and manually specify heading IDs next to each heading.