summaryrefslogtreecommitdiffstats
path: root/markup
diff options
context:
space:
mode:
authorBjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>2023-02-11 16:20:24 +0100
committerBjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>2023-02-21 17:56:41 +0100
commit90da7664bf1f3a0ca2e18144b5deacf532c6e3cf (patch)
tree78d8ac72ebb2ccee4ca4bbeeb9add3365c743e90 /markup
parent0afec0a9f4aace1f5f4af6822aeda6223ee3e3a9 (diff)
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
Diffstat (limited to 'markup')
-rw-r--r--markup/asciidocext/convert.go26
-rw-r--r--markup/asciidocext/convert_test.go82
-rw-r--r--markup/converter/converter.go2
-rw-r--r--markup/goldmark/convert.go10
-rw-r--r--markup/goldmark/toc.go10
-rw-r--r--markup/tableofcontents/tableofcontents.go110
-rw-r--r--markup/tableofcontents/tableofcontents_test.go85
7 files changed, 199 insertions, 126 deletions
diff --git a/markup/asciidocext/convert.go b/markup/asciidocext/convert.go
index 4c83e0e95..c9524778f 100644
--- 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 {
diff --git a/markup/asciidocext/convert_test.go b/markup/asciidocext/convert_test.go
index 3a350c5ce..47208c066 100644
--- 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\">")
}
diff --git a/markup/converter/converter.go b/markup/converter/converter.go
index c760381f4..7e5b56b07 100644
--- 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.
diff --git a/markup/goldmark/convert.go b/markup/goldmark/convert.go
index a179cd233..6c1c7ad0a 100644
--- 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
}
diff --git a/markup/goldmark/toc.go b/markup/goldmark/toc.go
index 396c1d071..ac5040e85 100644
--- 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 {
diff --git a/markup/tableofcontents/tableofcontents.go b/markup/tableofcontents/tableofcontents.go
index 2e7f47d20..bd0aaa801 100644
--- 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 == ""
+}
+
+func (h *Heading) walk(fn func(*Heading)) {
+ fn(h)
+ for _, h := range h.Headings {
+ h.walk(fn)
+ }
}
-// Root implements AddAt, which can be used to build the
-// data structure for the ToC.
-type Root struct {
+// 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")
diff --git a/markup/tableofcontents/tableofcontents_test.go b/markup/tableofcontents/tableofcontents_test.go
index daeb9f991..adbda4b00 100644
--- 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)
+ }
+ })
+
+}
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-07 23:29:26 +0000