feat: let a heading set its own id with {#id}

This commit is contained in:
tgiachi 2026-11-15 09:53:36 +01:00
commit a850e9ed41
2 changed files with 41 additions and 5 deletions

View file

@ -11,6 +11,7 @@ import (
"github.com/yuin/goldmark"
"github.com/yuin/goldmark/ast"
"github.com/yuin/goldmark/parser"
"github.com/yuin/goldmark/renderer/html"
"github.com/yuin/goldmark/text"
)
@ -28,11 +29,15 @@ type Heading struct {
// engine converts Markdown to HTML. Raw HTML is passed through because the
// pages use it for tables with data-label cells, hidden notes and the hero.
var engine = goldmark.New(goldmark.WithRendererOptions(html.WithUnsafe()))
var engine = goldmark.New(
goldmark.WithParserOptions(parser.WithHeadingAttribute()),
goldmark.WithRendererOptions(html.WithUnsafe()),
)
// Render converts md to HTML and returns the headings it found. Every heading
// from level 2 gets an id attribute made by Slug, with -2, -3 and so on for
// duplicates; the level 1 heading is the title of the page and gets none.
// Render converts md to HTML and returns the headings it found. A heading can
// set its own id with "## Title {#id}". Any other heading from level 2 gets an
// id made by Slug, with -2, -3 and so on for duplicates; the level 1 heading
// is the title of the page and gets none.
func Render(md string) (string, []Heading, error) {
src := []byte(md)
doc := engine.Parser().Parse(text.NewReader(src))
@ -46,7 +51,10 @@ func Render(md string) (string, []Heading, error) {
}
plain := plainText(h, src)
id := ""
if h.Level >= 2 {
if explicit, ok := h.AttributeString("id"); ok {
id = attributeText(explicit)
used[id]++
} else if h.Level >= 2 {
id = uniqueID(Slug(plain), used)
h.SetAttributeString("id", []byte(id))
}
@ -64,6 +72,17 @@ func Render(md string) (string, []Heading, error) {
return out.String(), headings, nil
}
// attributeText returns the text of a goldmark attribute value.
func attributeText(value any) string {
switch v := value.(type) {
case []byte:
return string(v)
case string:
return v
}
return ""
}
// uniqueID returns id, or id with a numeric suffix when it was already used.
func uniqueID(id string, used map[string]int) string {
used[id]++

View file

@ -82,6 +82,23 @@ func TestRenderTitleHasNoID(t *testing.T) {
}
}
// TestRenderExplicitHeadingID checks that "{#id}" after a heading sets its id
// and is not part of its text, and that other headings still get theirs.
func TestRenderExplicitHeadingID(t *testing.T) {
html, headings, err := Render("## Request an account {#account}\n\n## Other\n\n## Request an account\n")
if err != nil {
t.Fatal(err)
}
for _, want := range []string{`<h2 id="account">Request an account</h2>`, `<h2 id="other">Other</h2>`, `<h2 id="request-an-account">Request an account</h2>`} {
if !strings.Contains(html, want) {
t.Errorf("html %q does not contain %q", html, want)
}
}
if len(headings) != 3 || headings[0].ID != "account" || headings[0].Text != "Request an account" {
t.Errorf("headings = %+v", headings)
}
}
// TestRenderHeadingTextIsPlain checks that the heading text drops the markup.
func TestRenderHeadingTextIsPlain(t *testing.T) {
_, headings, err := Render("## Free *your* mind\n")