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

2 files changed, 35 insertions, 32 deletions

diff --git a/lazy/init.go b/lazy/init.go
index b998d0305..4de2a83f7 100644
--- a/lazy/init.go
+++ b/lazy/init.go
@@ -29,7 +29,7 @@ func New() *Init {
 
 // Init holds a graph of lazily initialized dependencies.
 type Init struct {
-	// Used in tests
+	// Used mainly for testing.
 	initCount uint64
 
 	mu sync.Mutex
@@ -40,11 +40,11 @@ type Init struct {
 	init onceMore
 	out  any
 	err  error
-	f    func() (any, error)
+	f    func(context.Context) (any, error)
 }
 
 // Add adds a func as a new child dependency.
-func (ini *Init) Add(initFn func() (any, error)) *Init {
+func (ini *Init) Add(initFn func(context.Context) (any, error)) *Init {
 	if ini == nil {
 		ini = New()
 	}
@@ -59,14 +59,14 @@ func (ini *Init) InitCount() int {
 
 // AddWithTimeout is same as Add, but with a timeout that aborts initialization.
 func (ini *Init) AddWithTimeout(timeout time.Duration, f func(ctx context.Context) (any, error)) *Init {
-	return ini.Add(func() (any, error) {
-		return ini.withTimeout(timeout, f)
+	return ini.Add(func(ctx context.Context) (any, error) {
+		return ini.withTimeout(ctx, timeout, f)
 	})
 }
 
 // Branch creates a new dependency branch based on an existing and adds
 // the given dependency as a child.
-func (ini *Init) Branch(initFn func() (any, error)) *Init {
+func (ini *Init) Branch(initFn func(context.Context) (any, error)) *Init {
 	if ini == nil {
 		ini = New()
 	}
@@ -75,13 +75,13 @@ func (ini *Init) Branch(initFn func() (any, error)) *Init {
 
 // BranchdWithTimeout is same as Branch, but with a timeout.
 func (ini *Init) BranchWithTimeout(timeout time.Duration, f func(ctx context.Context) (any, error)) *Init {
-	return ini.Branch(func() (any, error) {
-		return ini.withTimeout(timeout, f)
+	return ini.Branch(func(ctx context.Context) (any, error) {
+		return ini.withTimeout(ctx, timeout, f)
 	})
 }
 
 // Do initializes the entire dependency graph.
-func (ini *Init) Do() (any, error) {
+func (ini *Init) Do(ctx context.Context) (any, error) {
 	if ini == nil {
 		panic("init is nil")
 	}
@@ -92,7 +92,7 @@ func (ini *Init) Do() (any, error) {
 		if prev != nil {
 			// A branch. Initialize the ancestors.
 			if prev.shouldInitialize() {
-				_, err := prev.Do()
+				_, err := prev.Do(ctx)
 				if err != nil {
 					ini.err = err
 					return
@@ -105,12 +105,12 @@ func (ini *Init) Do() (any, error) {
 		}
 
 		if ini.f != nil {
-			ini.out, ini.err = ini.f()
+			ini.out, ini.err = ini.f(ctx)
 		}
 
 		for _, child := range ini.children {
 			if child.shouldInitialize() {
-				_, err := child.Do()
+				_, err := child.Do(ctx)
 				if err != nil {
 					ini.err = err
 					return
@@ -154,7 +154,7 @@ func (ini *Init) Reset() {
 	}
 }
 
-func (ini *Init) add(branch bool, initFn func() (any, error)) *Init {
+func (ini *Init) add(branch bool, initFn func(context.Context) (any, error)) *Init {
 	ini.mu.Lock()
 	defer ini.mu.Unlock()
 
@@ -179,8 +179,8 @@ func (ini *Init) checkDone() {
 	}
 }
 
-func (ini *Init) withTimeout(timeout time.Duration, f func(ctx context.Context) (any, error)) (any, error) {
-	ctx, cancel := context.WithTimeout(context.Background(), timeout)
+func (ini *Init) withTimeout(ctx context.Context, timeout time.Duration, f func(ctx context.Context) (any, error)) (any, error) {
+	ctx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 	c := make(chan verr, 1)
 
diff --git a/lazy/init_test.go b/lazy/init_test.go
index 4d871b937..499ea2cce 100644
--- a/lazy/init_test.go
+++ b/lazy/init_test.go
@@ -48,16 +48,16 @@ func TestInit(t *testing.T) {
 
 	var result string
 
-	f1 := func(name string) func() (any, error) {
-		return func() (any, error) {
+	f1 := func(name string) func(context.Context) (any, error) {
+		return func(context.Context) (any, error) {
 			result += name + "|"
 			doWork()
 			return name, nil
 		}
 	}
 
-	f2 := func() func() (any, error) {
-		return func() (any, error) {
+	f2 := func() func(context.Context) (any, error) {
+		return func(context.Context) (any, error) {
 			doWork()
 			return nil, nil
 		}
@@ -75,6 +75,8 @@ func TestInit(t *testing.T) {
 
 	var wg sync.WaitGroup
 
+	ctx := context.Background()
+
 	// Add some concurrency and randomness to verify thread safety and
 	// init order.
 	for i := 0; i < 100; i++ {
@@ -83,20 +85,20 @@ func TestInit(t *testing.T) {
 			defer wg.Done()
 			var err error
 			if rnd.Intn(10) < 5 {
-				_, err = root.Do()
+				_, err = root.Do(ctx)
 				c.Assert(err, qt.IsNil)
 			}
 
 			// Add a new branch on the fly.
 			if rnd.Intn(10) > 5 {
 				branch := branch1_2.Branch(f2())
-				_, err = branch.Do()
+				_, err = branch.Do(ctx)
 				c.Assert(err, qt.IsNil)
 			} else {
-				_, err = branch1_2_1.Do()
+				_, err = branch1_2_1.Do(ctx)
 				c.Assert(err, qt.IsNil)
 			}
-			_, err = branch1_2.Do()
+			_, err = branch1_2.Do(ctx)
 			c.Assert(err, qt.IsNil)
 		}(i)
 
@@ -114,7 +116,7 @@ func TestInitAddWithTimeout(t *testing.T) {
 		return nil, nil
 	})
 
-	_, err := init.Do()
+	_, err := init.Do(context.Background())
 
 	c.Assert(err, qt.IsNil)
 }
@@ -133,7 +135,7 @@ func TestInitAddWithTimeoutTimeout(t *testing.T) {
 		return nil, nil
 	})
 
-	_, err := init.Do()
+	_, err := init.Do(context.Background())
 
 	c.Assert(err, qt.Not(qt.IsNil))
 
@@ -149,7 +151,7 @@ func TestInitAddWithTimeoutError(t *testing.T) {
 		return nil, errors.New("failed")
 	})
 
-	_, err := init.Do()
+	_, err := init.Do(context.Background())
 
 	c.Assert(err, qt.Not(qt.IsNil))
 }
@@ -178,8 +180,8 @@ func TestInitBranchOrder(t *testing.T) {
 
 	base := New()
 
-	work := func(size int, f func()) func() (any, error) {
-		return func() (any, error) {
+	work := func(size int, f func()) func(context.Context) (any, error) {
+		return func(context.Context) (any, error) {
 			doWorkOfSize(size)
 			if f != nil {
 				f()
@@ -205,13 +207,14 @@ func TestInitBranchOrder(t *testing.T) {
 	}
 
 	var wg sync.WaitGroup
+	ctx := context.Background()
 
 	for _, v := range inits {
 		v := v
 		wg.Add(1)
 		go func() {
 			defer wg.Done()
-			_, err := v.Do()
+			_, err := v.Do(ctx)
 			c.Assert(err, qt.IsNil)
 		}()
 	}
@@ -225,17 +228,17 @@ func TestInitBranchOrder(t *testing.T) {
 func TestResetError(t *testing.T) {
 	c := qt.New(t)
 	r := false
-	i := New().Add(func() (any, error) {
+	i := New().Add(func(context.Context) (any, error) {
 		if r {
 			return nil, nil
 		}
 		return nil, errors.New("r is false")
 	})
-	_, err := i.Do()
+	_, err := i.Do(context.Background())
 	c.Assert(err, qt.IsNotNil)
 	i.Reset()
 	r = true
-	_, err = i.Do()
+	_, err = i.Do(context.Background())
 	c.Assert(err, qt.IsNil)
 
 }