wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Generate ToC with Hugo rather than JavaScript (#1851)

Browse source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2024-06-11 23:24:23 +02:00 • committed by GitHub
parent a7a7eadf2c
commit 784b8984f3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 148 additions and 214 deletions
Download patch file Download diff file Expand all files Collapse all files

170
static/js/toc.js
View file

@ -14,174 +14,6 @@ See the License for the specific language governing permissions and
limitations under the License.
*/
/*
Account for id attributes that are in the sidebar nav
*/
function populateIds() {
const navItems = document.querySelectorAll(".td-sidebar-nav li");
return Array.from(navItems).map(item => item.id).filter(id => id != "");
}
/*
Given an ID and an array of IDs, return s version of the original ID that's
not equal to any of the IDs in the array.
*/
function uniquifyHeadingId(id, uniqueIDs) {
const baseId = id;
let counter = 0;
while (uniqueIDs.includes(id)) {
counter = counter + 1;
id = baseId + "-" + counter.toString();
}
return id;
}
/*
Given an array of heading nodes, ensure they all have unique IDs.
We have to do this mostly because of client-server modules, which are
rendered separately then glued together with a template.
Because heading IDs are generated in rendering, this means they can and will
end up with duplicate IDs.
*/
function uniquifyHeadingIds(headings) {
const uniqueIDs = populateIds();
for (let heading of headings) {
const uniqueID = uniquifyHeadingId(heading.id, uniqueIDs);
uniqueIDs.push(uniqueID);
heading.id = uniqueID;
}
}
/*
The document contains "normal" headings, and these have corresponding items
in the ToC.
The document might also contain H1 headings that act as titles for blocks of
rendered data, like HTTP APIs or event schemas. Unlike "normal" headings,
these headings don't appear in the ToC. But they do have anchor IDs to enable
links to them. When someone follows a link to one of these "rendered data"
headings we want to scroll the ToC to the item corresponding to the "normal"
heading preceding the "rendered data" heading we have visited.
To support this we need to add `data` attributes to ToC items.
These attributes identify which "rendered data" headings live underneath
the heading corresponding to that ToC item.
*/
function setTocItemChildren(toc, headings) {
let tocEntryForHeading = null;
for (const heading of headings) {
// H1 headings are rendered-data headings
if (heading.tagName !== "H1") {
tocEntryForHeading = document.querySelector(`nav li a[href="#${heading.id}"]`);
} else {
// on the ToC entry for the parent heading,
// set a data-* attribute whose name is the child's fragment ID
tocEntryForHeading.setAttribute(`data-${heading.id}`, "true");
}
}
}
/*
Generate a table of contents based on the headings in the document.
*/
function makeToc() {
// make the title from the H1
const h1 = document.body.querySelector("h1");
const title = document.createElement("a");
title.id = "toc-title";
title.setAttribute("href", "#");
title.textContent = h1.textContent;
// make the content
const content = document.body.querySelector(".td-content");
let headings = [].slice.call(content.querySelectorAll("h2, h3, h4, h5, h6, .rendered-data > details > summary > h1"));
// exclude headings that don't have IDs.
headings = headings.filter(heading => heading.id);
uniquifyHeadingIds(headings);
// exclude .rendered-data > h1 headings from the ToC
const tocTargets = headings.filter(heading => heading.tagName !== "H1");
// we have to adjust heading IDs to ensure that they are unique
const nav = document.createElement("nav");
nav.id = "TableOfContents";
const section = makeTocSection(tocTargets, 0);
nav.appendChild(section.content);
// build the TOC and append to it title and content
const toc = document.createElement("div");
toc.id = "toc";
toc.appendChild(title);
toc.appendChild(nav);
// append TOC to the section navigation
const section_nav = document.body.querySelector("#td-section-nav");
let hr = document.createElement("hr");
section_nav.appendChild(hr);
section_nav.appendChild(toc);
// tell ToC items about any rendered-data headings they contain
setTocItemChildren(section.content, headings);
}
// create a single ToC entry
function makeTocEntry(heading) {
const li = document.createElement("li");
const a = document.createElement("a");
a.setAttribute("href", `#${heading.id}`);
a.textContent = heading.textContent;
li.appendChild(a);
return li;
}
/*
Each ToC section is an `<ol>` element.
ToC entries are `<li>` elements and these contain nested ToC sections,
whenever we go to the next heading level down.
*/
function makeTocSection(headings, index) {
const ol = document.createElement("ol");
let previousHeading = null;
let previousLi = null;
let i = index;
const lis = [];
for (i; i < headings.length; i++) {
const thisHeading = headings[i];
if (previousHeading && (thisHeading.tagName > previousHeading.tagName)) {
// we are going down a heading level, create a new nested section
const section = makeTocSection(headings, i);
previousLi.appendChild(section.content);
i = section.index -1;
}
else if (previousHeading && (previousHeading.tagName > thisHeading.tagName)) {
// we have come back up a level, so a section is finished
for (let li of lis) {
ol.appendChild(li);
}
return {
content: ol,
index: i
}
}
else {
// we are still processing this section, so add this heading to the current section
previousLi = makeTocEntry(thisHeading);
lis.push(previousLi);
previousHeading = thisHeading;
}
}
for (let li of lis) {
ol.appendChild(li);
}
return {
content: ol,
index: i
}
}
/*
Set a new ToC entry.
Clear any previously highlighted ToC items, set the new one,
@ -303,8 +135,6 @@ for the corresponding ToC entry.
*/
window.addEventListener('DOMContentLoaded', () => {
makeToc();
const toc = document.querySelector("#toc");
toc.addEventListener("click", event => {
if (event.target.tagName === "A") {