Skip to content

anchors in headings #584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
soloio-bulldozer merged 2 commits into from
Sep 23, 2025
Merged

anchors in headings #584

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5e29372
anchors in headings
artberger Sep 22, 2025
766c825
changelog
artberger Sep 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions changelog/v0.39.4/docs-anchor2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
changelog:
- type: FIX
issueLink: https://github.com/solo-io/doctopus/issues/124
resolvesIssue: true
description: >-
Fix a bug where headings on the same doc page have the same anchor and hence do not work. Numbers anchors for the same headings sequentially. The headings were not getting numbered from the previous PR.
13 changes: 12 additions & 1 deletion pkg/code-generator/docgen/funcs/template_funcs.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,18 @@ func TemplateFuncs(project *model.Project, docsOptions *options.DocsOptions) tem

func toHeading(docsOptions *options.DocsOptions) func(format string, p *string) string {
if docsOptions.Output == options.Hugo {
return printPointer
// For Hugo, we need to generate the same numbered anchors as toAnchorLink
// Track anchor names to handle duplicates
anchorCounts := make(map[string]int)
Copy link

@andy-fong andy-fong Sep 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At first, this looks a bit strange but is the idea that anchorCounts is declare here because toHeading() is called only once and anchorCounts get "auto"captured into the returned function and that's the function that will get called multiple times? That's a clever hack without local static like in C++.

Copy link
Contributor Author

@artberger artberger Sep 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah the toHeading is called once during the template setup, but this returned function is called for each heading instance. We needed separate anchorCounts funcs under both toHeading and toAnchorLink because they were counting different things (headings vs anchors), so to keep them in sync so the headings match the anchor counts. Before without this, it was only counting the anchors and replacing it for non-heading links 😅

return func(format string, p *string) string {
val := printPointer(format, p)
name := strings.ToLower(val)
anchorCounts[name]++
if anchorCounts[name] > 1 {
return fmt.Sprintf("%s {#%s-%d}", val, name, anchorCounts[name]-1)
}
return fmt.Sprintf("%s {#%s}", val, name)
}
} else {
// Track anchor names to handle duplicates
anchorCounts := make(map[string]int)
Expand Down