From a850e9ed41c6be30bad9d0e572a00ddfa1f050fe Mon Sep 17 00:00:00 2001 From: tgiachi Date: Sun, 15 Nov 2026 09:53:36 +0100 Subject: [PATCH] feat: let a heading set its own id with {#id} --- internal/mdx/mdx.go | 29 ++++++++++++++++++++++++----- internal/mdx/mdx_test.go | 17 +++++++++++++++++ 2 files changed, 41 insertions(+), 5 deletions(-) diff --git a/internal/mdx/mdx.go b/internal/mdx/mdx.go index 8d6d0e4..f79f644 100644 --- a/internal/mdx/mdx.go +++ b/internal/mdx/mdx.go @@ -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]++ diff --git a/internal/mdx/mdx_test.go b/internal/mdx/mdx_test.go index f60f8b6..3173977 100644 --- a/internal/mdx/mdx_test.go +++ b/internal/mdx/mdx_test.go @@ -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{`

Request an account

`, `

Other

`, `

Request an account

`} { + 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")