Skip to content

Generate IDs for sectionless headings, and improve/fix existing IDs #4523

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Generate IDs for sectionless headings, and improve/fix existing IDs #4523

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d5c5078
Generate IDs for sectionless headings, and improve/fix existing IDs
kfranqueiro Aug 7, 2025
3d40f5c
Fix previously-broken section links in Understanding Techniques
kfranqueiro Aug 18, 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
15 changes: 12 additions & 3 deletions 11ty/CustomLiquid.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { type Options as SlugifyOptions, slugifyWithCounter } from "@sindresorhus/slugify";
import { Liquid, type Template } from "liquidjs";
import type { LiquidOptions, RenderOptions } from "liquidjs/dist/liquid-options";
import compact from "lodash-es/compact";
Expand All @@ -9,7 +10,6 @@ import type { GlobalData } from "eleventy.config";

import { biblioPattern, getBiblio, getXmlBiblio } from "./biblio";
import { flattenDom, load, type CheerioAnyNode } from "./cheerio";
import { generateId } from "./common";
import { getAcknowledgementsForVersion, type TermsMap } from "./guidelines";
import { resolveTechniqueIdFromHref, understandingToTechniqueLinkSelector } from "./techniques";
import { techniqueToUnderstandingLinkSelector } from "./understanding";
Expand Down Expand Up @@ -638,6 +638,9 @@ export class CustomLiquid extends Liquid {
} else $("section#references").remove();
}

const slugify = slugifyWithCounter();
const slugifyOptions: SlugifyOptions = { decamelize: false };

// Allow autogenerating missing top-level section IDs in understanding docs,
// but don't pick up incorrectly-nested sections in some techniques pages (e.g. H91)
const sectionSelector = scope.isUnderstanding ? "section" : "section[id]:not(.obsolete)";
Expand All @@ -648,7 +651,8 @@ export class CustomLiquid extends Liquid {
// when we have sections and sidebar skeleton already reordered
const $tocList = $(".sidebar nav ul");
$h2Sections.each((_, el) => {
if (!el.attribs.id) el.attribs.id = generateId($(el).find(sectionH2Selector).text());
if (!el.attribs.id)
el.attribs.id = slugify($(el).find(sectionH2Selector).text(), slugifyOptions);
$("<a></a>")
.attr("href", `#${el.attribs.id}`)
.text(normalizeTocLabel($(el).find(sectionH2Selector).text()))
Expand All @@ -672,9 +676,14 @@ export class CustomLiquid extends Liquid {
$(autoIdSectionSelectors.join(", "))
.filter(`:has(${sectionHeadingSelector})`)
.each((_, el) => {
el.attribs.id = generateId($(el).find(sectionHeadingSelector).text());
el.attribs.id = slugify($(el).find(sectionHeadingSelector).text(), slugifyOptions);
});

// Also autogenerate IDs for any headings with no dedicated section nor explicit ID
$(":is(h3, h4, h5):not(:first-child):not([id])").each((_, el) => {
el.attribs.id = slugify($(el).text(), slugifyOptions);
});

return stripHtmlComments($.html());
}
}
1 change: 1 addition & 0 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
"license": "W3C",
"dependencies": {
"@11ty/eleventy": "^3.1.2",
"@sindresorhus/slugify": "^2.2.1",
"axios": "^1.11.0",
"cheerio": "^1.0.0",
"glob": "^10.3.16",
Expand Down