Add page fragments support to Related

The main topic of this commit is that you can now index fragments (content heading identifiers) when calling `.Related`. You can do this by: * Configure one or more indices with type `fragments` * The name of those index configurations maps to an (optional) front matter slice with fragment references. This allows you to link page<->fragment and page<->page. * This also will index all the fragments (heading identifiers) of the pages. It's also possible to use type `fragments` indices in shortcode, e.g.: ``` {{ $related := site.RegularPages.Related .Page }} ``` But, and this is important, you need to include the shortcode using the `{{<` delimiter. Not doing so will create infinite loops and timeouts. This commit also: * Adds two new methods to Page: Fragments (can also be used to build ToC) and HeadingsFiltered (this is only used in Related Content with index type `fragments` and `enableFilter` set to true. * Consolidates all `.Related*` methods into one, which takes either a `Page` or an options map as its only argument. * Add `context.Context` to all of the content related Page API. Turns out it wasn't strictly needed for this particular feature, but it will soon become usefil, e.g. in #9339. Closes #10711 Updates #9339 Updates #10725
2025-08-19 21:21:39 +02:00 · 2023-02-11 16:20:24 +01:00
parent 0afec0a9f4
commit 90da7664bf
66 changed files with 1363 additions and 829 deletions
--- a/markup/asciidocext/convert.go
+++ b/markup/asciidocext/convert.go
@@ -53,10 +53,10 @@ func (p provider) New(cfg converter.ProviderConfig) (converter.Provider, error)

 type asciidocResult struct {
 	converter.Result
-	toc tableofcontents.Root
+	toc *tableofcontents.Fragments
 }

-func (r asciidocResult) TableOfContents() tableofcontents.Root {
+func (r asciidocResult) TableOfContents() *tableofcontents.Fragments {
 	return r.toc
 }

@@ -205,16 +205,16 @@ func hasAsciiDoc() bool {

 // extractTOC extracts the toc from the given src html.
 // It returns the html without the TOC, and the TOC data
-func (a *asciidocConverter) extractTOC(src []byte) ([]byte, tableofcontents.Root, error) {
+func (a *asciidocConverter) extractTOC(src []byte) ([]byte, *tableofcontents.Fragments, error) {
 	var buf bytes.Buffer
 	buf.Write(src)
 	node, err := html.Parse(&buf)
 	if err != nil {
-		return nil, tableofcontents.Root{}, err
+		return nil, nil, err
 	}
 	var (
 		f       func(*html.Node) bool
-		toc     tableofcontents.Root
+		toc     *tableofcontents.Fragments
 		toVisit []*html.Node
 	)
 	f = func(n *html.Node) bool {
@@ -242,12 +242,12 @@ func (a *asciidocConverter) extractTOC(src []byte) ([]byte, tableofcontents.Root
 	}
 	f(node)
 	if err != nil {
-		return nil, tableofcontents.Root{}, err
+		return nil, nil, err
 	}
 	buf.Reset()
 	err = html.Render(&buf, node)
 	if err != nil {
-		return nil, tableofcontents.Root{}, err
+		return nil, nil, err
 	}
 	// ltrim <html><head></head><body> and rtrim </body></html> which are added by html.Render
 	res := buf.Bytes()[25:]
@@ -256,9 +256,9 @@ func (a *asciidocConverter) extractTOC(src []byte) ([]byte, tableofcontents.Root
 }

 // parseTOC returns a TOC root from the given toc Node
-func parseTOC(doc *html.Node) tableofcontents.Root {
+func parseTOC(doc *html.Node) *tableofcontents.Fragments {
 	var (
-		toc tableofcontents.Root
+		toc tableofcontents.Builder
 		f   func(*html.Node, int, int)
 	)
 	f = func(n *html.Node, row, level int) {
@@ -276,9 +276,9 @@ func parseTOC(doc *html.Node) tableofcontents.Root {
 						continue
 					}
 					href := attr(c, "href")[1:]
-					toc.AddAt(tableofcontents.Heading{
-						Text: nodeContent(c),
-						ID:   href,
+					toc.AddAt(&tableofcontents.Heading{
+						Title: nodeContent(c),
+						ID:    href,
 					}, row, level)
 				}
 				f(n.FirstChild, row, level)
@@ -289,7 +289,7 @@ func parseTOC(doc *html.Node) tableofcontents.Root {
 		}
 	}
 	f(doc.FirstChild, -1, 0)
-	return toc
+	return toc.Build()
 }

 func attr(node *html.Node, key string) string {
--- a/markup/asciidocext/convert_test.go
+++ b/markup/asciidocext/convert_test.go
@@ -21,13 +21,13 @@ import (
 	"path/filepath"
 	"testing"

+	"github.com/gohugoio/hugo/common/collections"
 	"github.com/gohugoio/hugo/common/hexec"
 	"github.com/gohugoio/hugo/common/loggers"
 	"github.com/gohugoio/hugo/config"
 	"github.com/gohugoio/hugo/config/security"
 	"github.com/gohugoio/hugo/markup/converter"
 	"github.com/gohugoio/hugo/markup/markup_config"
-	"github.com/gohugoio/hugo/markup/tableofcontents"

 	qt "github.com/frankban/quicktest"
 )
@@ -343,49 +343,8 @@ testContent
 	c.Assert(err, qt.IsNil)
 	toc, ok := r.(converter.TableOfContentsProvider)
 	c.Assert(ok, qt.Equals, true)
-	expected := tableofcontents.Root{
-		Headings: tableofcontents.Headings{
-			{
-				ID:   "",
-				Text: "",
-				Headings: tableofcontents.Headings{
-					{
-						ID:       "_introduction",
-						Text:     "Introduction",
-						Headings: nil,
-					},
-					{
-						ID:   "_section_1",
-						Text: "Section 1",
-						Headings: tableofcontents.Headings{
-							{
-								ID:   "_section_1_1",
-								Text: "Section 1.1",
-								Headings: tableofcontents.Headings{
-									{
-										ID:       "_section_1_1_1",
-										Text:     "Section 1.1.1",
-										Headings: nil,
-									},
-								},
-							},
-							{
-								ID:       "_section_1_2",
-								Text:     "Section 1.2",
-								Headings: nil,
-							},
-						},
-					},
-					{
-						ID:       "_section_2",
-						Text:     "Section 2",
-						Headings: nil,
-					},
-				},
-			},
-		},
-	}
-	c.Assert(toc.TableOfContents(), qt.DeepEquals, expected)
+
+	c.Assert(toc.TableOfContents().Identifiers, qt.DeepEquals, collections.SortedStringSlice{"_introduction", "_section_1", "_section_1_1", "_section_1_1_1", "_section_1_2", "_section_2"})
 	c.Assert(string(r.Bytes()), qt.Not(qt.Contains), "<div id=\"toc\" class=\"toc\">")
 }

@@ -404,22 +363,7 @@ func TestTableOfContentsWithCode(t *testing.T) {
 	c.Assert(err, qt.IsNil)
 	toc, ok := r.(converter.TableOfContentsProvider)
 	c.Assert(ok, qt.Equals, true)
-	expected := tableofcontents.Root{
-		Headings: tableofcontents.Headings{
-			{
-				ID:   "",
-				Text: "",
-				Headings: tableofcontents.Headings{
-					{
-						ID:       "_some_code_in_the_title",
-						Text:     "Some <code>code</code> in the title",
-						Headings: nil,
-					},
-				},
-			},
-		},
-	}
-	c.Assert(toc.TableOfContents(), qt.DeepEquals, expected)
+	c.Assert(toc.TableOfContents().HeadingsMap["_some_code_in_the_title"].Title, qt.Equals, "Some <code>code</code> in the title")
 	c.Assert(string(r.Bytes()), qt.Not(qt.Contains), "<div id=\"toc\" class=\"toc\">")
 }

@@ -443,21 +387,7 @@ func TestTableOfContentsPreserveTOC(t *testing.T) {
 	c.Assert(err, qt.IsNil)
 	toc, ok := r.(converter.TableOfContentsProvider)
 	c.Assert(ok, qt.Equals, true)
-	expected := tableofcontents.Root{
-		Headings: tableofcontents.Headings{
-			{
-				ID:   "",
-				Text: "",
-				Headings: tableofcontents.Headings{
-					{
-						ID:       "some-title",
-						Text:     "Some title",
-						Headings: nil,
-					},
-				},
-			},
-		},
-	}
-	c.Assert(toc.TableOfContents(), qt.DeepEquals, expected)
+
+	c.Assert(toc.TableOfContents().Identifiers, qt.DeepEquals, collections.SortedStringSlice{"some-title"})
 	c.Assert(string(r.Bytes()), qt.Contains, "<div id=\"toc\" class=\"toc\">")
 }
--- a/markup/converter/converter.go
+++ b/markup/converter/converter.go
@@ -101,7 +101,7 @@ type DocumentInfo interface {

 // TableOfContentsProvider provides the content as a ToC structure.
 type TableOfContentsProvider interface {
-	TableOfContents() tableofcontents.Root
+	TableOfContents() *tableofcontents.Fragments
 }

 // AnchorNameSanitizer tells how a converter sanitizes anchor names.
--- a/markup/goldmark/convert.go
+++ b/markup/goldmark/convert.go
@@ -160,11 +160,11 @@ var _ identity.IdentitiesProvider = (*converterResult)(nil)

 type converterResult struct {
 	converter.Result
-	toc tableofcontents.Root
+	toc *tableofcontents.Fragments
 	ids identity.Identities
 }

-func (c converterResult) TableOfContents() tableofcontents.Root {
+func (c converterResult) TableOfContents() *tableofcontents.Fragments {
 	return c.toc
 }

@@ -228,9 +228,9 @@ type parserContext struct {
 	parser.Context
 }

-func (p *parserContext) TableOfContents() tableofcontents.Root {
+func (p *parserContext) TableOfContents() *tableofcontents.Fragments {
 	if v := p.Get(tocResultKey); v != nil {
-		return v.(tableofcontents.Root)
+		return v.(*tableofcontents.Fragments)
 	}
-	return tableofcontents.Root{}
+	return nil
 }
--- a/markup/goldmark/toc.go
+++ b/markup/goldmark/toc.go
@@ -41,8 +41,8 @@ func (t *tocTransformer) Transform(n *ast.Document, reader text.Reader, pc parse
 	}

 	var (
-		toc         tableofcontents.Root
-		tocHeading  tableofcontents.Heading
+		toc         tableofcontents.Builder
+		tocHeading  = &tableofcontents.Heading{}
 		level       int
 		row         = -1
 		inHeading   bool
@@ -53,10 +53,10 @@ func (t *tocTransformer) Transform(n *ast.Document, reader text.Reader, pc parse
 		s := ast.WalkStatus(ast.WalkContinue)
 		if n.Kind() == ast.KindHeading {
 			if inHeading && !entering {
-				tocHeading.Text = headingText.String()
+				tocHeading.Title = headingText.String()
 				headingText.Reset()
 				toc.AddAt(tocHeading, row, level-1)
-				tocHeading = tableofcontents.Heading{}
+				tocHeading = &tableofcontents.Heading{}
 				inHeading = false
 				return s, nil
 			}
@@ -106,7 +106,7 @@ func (t *tocTransformer) Transform(n *ast.Document, reader text.Reader, pc parse
 		return s, nil
 	})

-	pc.Set(tocResultKey, toc)
+	pc.Set(tocResultKey, toc.Build())
 }

 type tocExtension struct {
--- a/markup/tableofcontents/tableofcontents.go
+++ b/markup/tableofcontents/tableofcontents.go
@@ -14,35 +14,104 @@
 package tableofcontents

 import (
+	"sort"
 	"strings"
+
+	"github.com/gohugoio/hugo/common/collections"
 )

+// Empty is an empty ToC.
+var Empty = &Fragments{
+	Headings:    Headings{},
+	HeadingsMap: map[string]*Heading{},
+}
+
+// Builder is used to build the ToC data structure.
+type Builder struct {
+	toc *Fragments
+}
+
+// Add adds the heading to the ToC.
+func (b *Builder) AddAt(h *Heading, row, level int) {
+	if b.toc == nil {
+		b.toc = &Fragments{}
+	}
+	b.toc.addAt(h, row, level)
+}
+
+// Build returns the ToC.
+func (b Builder) Build() *Fragments {
+	if b.toc == nil {
+		return Empty
+	}
+	b.toc.HeadingsMap = make(map[string]*Heading)
+	b.toc.walk(func(h *Heading) {
+		if h.ID != "" {
+			b.toc.HeadingsMap[h.ID] = h
+			b.toc.Identifiers = append(b.toc.Identifiers, h.ID)
+		}
+	})
+	sort.Strings(b.toc.Identifiers)
+	return b.toc
+}
+
 // Headings holds the top level headings.
-type Headings []Heading
+type Headings []*Heading
+
+// FilterBy returns a new Headings slice with all headings that matches the given predicate.
+// For internal use only.
+func (h Headings) FilterBy(fn func(*Heading) bool) Headings {
+	var out Headings
+
+	for _, h := range h {
+		h.walk(func(h *Heading) {
+			if fn(h) {
+				out = append(out, h)
+			}
+		})
+	}
+	return out
+}

 // Heading holds the data about a heading and its children.
 type Heading struct {
-	ID   string
-	Text string
+	ID    string
+	Title string

 	Headings Headings
 }

 // IsZero is true when no ID or Text is set.
 func (h Heading) IsZero() bool {
-	return h.ID == "" && h.Text == ""
+	return h.ID == "" && h.Title == ""
 }

-// Root implements AddAt, which can be used to build the
-// data structure for the ToC.
-type Root struct {
+func (h *Heading) walk(fn func(*Heading)) {
+	fn(h)
+	for _, h := range h.Headings {
+		h.walk(fn)
+	}
+}
+
+// Fragments holds the table of contents for a page.
+type Fragments struct {
+	// Headings holds the top level headings.
 	Headings Headings
+
+	// Identifiers holds all the identifiers in the ToC as a sorted slice.
+	// Note that collections.SortedStringSlice has both a Contains and Count method
+	// that can be used to identify missing and duplicate IDs.
+	Identifiers collections.SortedStringSlice
+
+	// HeadingsMap holds all the headings in the ToC as a map.
+	// Note that with duplicate IDs, the last one will win.
+	HeadingsMap map[string]*Heading
 }

-// AddAt adds the heading into the given location.
-func (toc *Root) AddAt(h Heading, row, level int) {
+// addAt adds the heading into the given location.
+func (toc *Fragments) addAt(h *Heading, row, level int) {
 	for i := len(toc.Headings); i <= row; i++ {
-		toc.Headings = append(toc.Headings, Heading{})
+		toc.Headings = append(toc.Headings, &Heading{})
 	}

 	if level == 0 {
@@ -50,19 +119,22 @@ func (toc *Root) AddAt(h Heading, row, level int) {
 		return
 	}

-	heading := &toc.Headings[row]
+	heading := toc.Headings[row]

 	for i := 1; i < level; i++ {
 		if len(heading.Headings) == 0 {
-			heading.Headings = append(heading.Headings, Heading{})
+			heading.Headings = append(heading.Headings, &Heading{})
 		}
-		heading = &heading.Headings[len(heading.Headings)-1]
+		heading = heading.Headings[len(heading.Headings)-1]
 	}
 	heading.Headings = append(heading.Headings, h)
 }

 // ToHTML renders the ToC as HTML.
-func (toc Root) ToHTML(startLevel, stopLevel int, ordered bool) string {
+func (toc *Fragments) ToHTML(startLevel, stopLevel int, ordered bool) string {
+	if toc == nil {
+		return ""
+	}
 	b := &tocBuilder{
 		s:          strings.Builder{},
 		h:          toc.Headings,
@@ -74,6 +146,12 @@ func (toc Root) ToHTML(startLevel, stopLevel int, ordered bool) string {
 	return b.s.String()
 }

+func (toc Fragments) walk(fn func(*Heading)) {
+	for _, h := range toc.Headings {
+		h.walk(fn)
+	}
+}
+
 type tocBuilder struct {
 	s strings.Builder
 	h Headings
@@ -133,11 +211,11 @@ func (b *tocBuilder) writeHeadings(level, indent int, h Headings) {
 	}
 }

-func (b *tocBuilder) writeHeading(level, indent int, h Heading) {
+func (b *tocBuilder) writeHeading(level, indent int, h *Heading) {
 	b.indent(indent)
 	b.s.WriteString("<li>")
 	if !h.IsZero() {
-		b.s.WriteString("<a href=\"#" + h.ID + "\">" + h.Text + "</a>")
+		b.s.WriteString("<a href=\"#" + h.ID + "\">" + h.Title + "</a>")
 	}
 	b.writeHeadings(level, indent, h.Headings)
 	b.s.WriteString("</li>\n")
--- a/markup/tableofcontents/tableofcontents_test.go
+++ b/markup/tableofcontents/tableofcontents_test.go
@@ -17,18 +17,33 @@ import (
 	"testing"

 	qt "github.com/frankban/quicktest"
+	"github.com/gohugoio/hugo/common/collections"
 )

+var newTestTocBuilder = func() Builder {
+	var b Builder
+	b.AddAt(&Heading{Title: "Heading 1", ID: "h1-1"}, 0, 0)
+	b.AddAt(&Heading{Title: "1-H2-1", ID: "1-h2-1"}, 0, 1)
+	b.AddAt(&Heading{Title: "1-H2-2", ID: "1-h2-2"}, 0, 1)
+	b.AddAt(&Heading{Title: "1-H3-1", ID: "1-h2-2"}, 0, 2)
+	b.AddAt(&Heading{Title: "Heading 2", ID: "h1-2"}, 1, 0)
+	return b
+}
+
+var newTestToc = func() *Fragments {
+	return newTestTocBuilder().Build()
+}
+
 func TestToc(t *testing.T) {
 	c := qt.New(t)

-	toc := &Root{}
+	toc := &Fragments{}

-	toc.AddAt(Heading{Text: "Heading 1", ID: "h1-1"}, 0, 0)
-	toc.AddAt(Heading{Text: "1-H2-1", ID: "1-h2-1"}, 0, 1)
-	toc.AddAt(Heading{Text: "1-H2-2", ID: "1-h2-2"}, 0, 1)
-	toc.AddAt(Heading{Text: "1-H3-1", ID: "1-h2-2"}, 0, 2)
-	toc.AddAt(Heading{Text: "Heading 2", ID: "h1-2"}, 1, 0)
+	toc.addAt(&Heading{Title: "Heading 1", ID: "h1-1"}, 0, 0)
+	toc.addAt(&Heading{Title: "1-H2-1", ID: "1-h2-1"}, 0, 1)
+	toc.addAt(&Heading{Title: "1-H2-2", ID: "1-h2-2"}, 0, 1)
+	toc.addAt(&Heading{Title: "1-H3-1", ID: "1-h2-2"}, 0, 2)
+	toc.addAt(&Heading{Title: "Heading 2", ID: "h1-2"}, 1, 0)

 	got := toc.ToHTML(1, -1, false)
 	c.Assert(got, qt.Equals, `<nav id="TableOfContents">
@@ -97,11 +112,11 @@ func TestToc(t *testing.T) {
 func TestTocMissingParent(t *testing.T) {
 	c := qt.New(t)

-	toc := &Root{}
+	toc := &Fragments{}

-	toc.AddAt(Heading{Text: "H2", ID: "h2"}, 0, 1)
-	toc.AddAt(Heading{Text: "H3", ID: "h3"}, 1, 2)
-	toc.AddAt(Heading{Text: "H3", ID: "h3"}, 1, 2)
+	toc.addAt(&Heading{Title: "H2", ID: "h2"}, 0, 1)
+	toc.addAt(&Heading{Title: "H3", ID: "h3"}, 1, 2)
+	toc.addAt(&Heading{Title: "H3", ID: "h3"}, 1, 2)

 	got := toc.ToHTML(1, -1, false)
 	c.Assert(got, qt.Equals, `<nav id="TableOfContents">
@@ -153,3 +168,53 @@ func TestTocMissingParent(t *testing.T) {
  </ol>
 </nav>`, qt.Commentf(got))
 }
+
+func TestTocMisc(t *testing.T) {
+	c := qt.New(t)
+
+	c.Run("Identifiers", func(c *qt.C) {
+		toc := newTestToc()
+		c.Assert(toc.Identifiers, qt.DeepEquals, collections.SortedStringSlice{"1-h2-1", "1-h2-2", "1-h2-2", "h1-1", "h1-2"})
+	})
+
+	c.Run("HeadingsMap", func(c *qt.C) {
+		toc := newTestToc()
+		m := toc.HeadingsMap
+		c.Assert(m["h1-1"].Title, qt.Equals, "Heading 1")
+		c.Assert(m["doesnot exist"], qt.IsNil)
+	})
+}
+
+func BenchmarkToc(b *testing.B) {
+
+	newTocs := func(n int) []*Fragments {
+		var tocs []*Fragments
+		for i := 0; i < n; i++ {
+			tocs = append(tocs, newTestToc())
+		}
+		return tocs
+	}
+
+	b.Run("Build", func(b *testing.B) {
+		var builders []Builder
+		for i := 0; i < b.N; i++ {
+			builders = append(builders, newTestTocBuilder())
+		}
+		b.ResetTimer()
+
+		for i := 0; i < b.N; i++ {
+			b := builders[i]
+			b.Build()
+		}
+	})
+
+	b.Run("ToHTML", func(b *testing.B) {
+		tocs := newTocs(b.N)
+		b.ResetTimer()
+		for i := 0; i < b.N; i++ {
+			toc := tocs[i]
+			toc.ToHTML(1, -1, false)
+		}
+	})
+
+}