3f:null 40:["$","title",null,{"children":"table of contents | Riley | Observable"}] 46:Tb14,# table of contents This notebook can generate a table of contents, with indentations, automatically for your notebook. ## origin Thanks to [Mike Bostock](/@mbostock "@mbostock") for creating the [original version](/@mbostock/toc "TOC") of the library and to [Bryan Hughes](/@nebrius "@nebrius") for adapting his code to [add indentation](/@nebrius/indented-toc "Indented ToC")! This code is a total rewrite that avoids using a [generator](/@observablehq/introduction-to-generators "Introduction to Generators") and avoids writing and parsing HTML.

improvements

Rather than using a [generator](/@observablehq/introduction-to-generators "Introduction to Generators") and yielding a new ToC element each time, the element is only returned once, and the [MutationObserver](//developer.Mozilla.org/en-US/docs/Web/API/MutationObserver "MutationObserver API") is just used to replace the list items. Instead of assembling the HTML syntax with strings and then parsing it with [HTL](/@observablehq/htl "Hypertext Literal"), each element is created separately, and nodes are appended and indented as necessary. Individually wrapped event listeners per heading have been replaced with one listener, using [event delegation](//developer.Mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_delegation "Building blocks: Events: Event delegation"). Previous versions only allowed [true heading elements](//developer.Mozilla.org/en-US/docs/Web/API/HTMLHeadingElement "HTMLHeadingElement") to be used; this version allows any CSS selector to be used, and in any order. The skip option [added](/@nebrius/indented-toc "Indented ToC") by [Bryan Hughes](/@nebrius "@nebrius") has been replaced with the filter option, which behaves nearly the same as the skip option when given the same values. When filter is a function, only headings that pass the filter are listed. Instead of using [`textContent`](//developer.Mozilla.org/en-US/docs/Web/API/Node/textContent "Node.prototype.textContent") to make an item display, the heading nodes’ contents are deeply copied into the link elements, to preserve formatting as much as possible. Lastly, lots of options have been added to customise behavior and appearance!

47:T4b3,## API `${ToC.name}()` has the following defaults. - headers: ["h2", "h3", "h4", "h5", "h6"] - title: null - skip: [] - ID: false - root: document.body.querySelector(".observablehq-root") ?? document.body - class: undefined - view: false - maxLength: Infinity - ~~order: undefined~~ - ~~orderDepth: 0~~ - scroll:

{
    behavior: "smooth"
    block: "start"
    inline: "start"
}

48:T1d26,ToC = { // This is a collection of all of the ToC elements. This is used to prevent feedback loops in which headers are found inside of a ToC element. const registry = new Set(); invalidation.then(() => registry.clear()); return function ToC({ headers: selectors = ["h2", "h3", "h4", "h5", "h6"], title, filter, ID: id = false, root = (document.body.querySelector(".observablehq-root") ?? document.body), class: className, view = false, scroll: { behavior: scrollBehavior = "smooth", block: scrollBlock = "start", inline: scrollInline = "start" } = {}, order = false, orderDepth, modify, maxLength: undefined, invalidation } = {}) { // # initialise options // ## initialise scroll options const scrollOpts = id ? undefined : Object.freeze({ behavior: scrollBehavior, block: scrollBlock, inline: scrollInline }); scrollBehavior = scrollBlock = scrollInline = undefined; // ## initialise selectors // convert selectors from string or iterable to array if (typeof selectors == "string" || selectors instanceof String) { selectors = [selectors]; } else if (!Array.isArray(selectors) && typeof selectors == "object" && Symbol.iterator in selectors) { selectors = [...selectors]; } // ## initialise filter // allow filter to be specified as either a string or string array to exclude or a function to include // The filter ends up being a function or falsy. if (filter && !(typeof filter === "function" || filter instanceof Function)) { if (Array.isArray(filter) || (filter != null && !(typeof filter == "string" || filter instanceof String) && Symbol.iterator in filter)) { let filterElements = new Set((Array.isArray(filter) ? filter : [...filter]).map(s => `${s}`.trim())); filter = ({textContent: text}) => !filterElements.has(text.trim()); } else { let filterElement = filter; filter = ({textContent: text}) => filterElement != text.trim(); } } // ## initialise order & orderDepth if ((typeof order == "number" || order instanceof Number) && (order = order.valueOf()) >= 0 && Number.isInteger(order)) { order = order.valueOf(); orderDepth = (typeof orderDepth == "number" || orderDepth instanceof Number) ? orderDepth.valueOf() : Infinity; orderDepth == 0 && (order = false); } else { order = false; orderDepth = undefined; } // # construct contents const contents = document.createElement(title ? "section" : order !== false ? "ol" : "ul"); const rootList = title ? document.createElement(order !== false ? "ol" : "ul") : contents; (order !== false && order != 1) && (rootList.start = order); if (title) { if (title instanceof Node) { contents.append(title); } else { let titleElm = document.createElement("strong"); titleElm.append(title); contents.append(titleElm); } contents.append(rootList); } className && contents.classList.append(...(Array.isArray(className) ? className : (className = [className]))); view && Object.defineProperty(contents, "value", { get: function value() { return headings.map(heading => [heading, selectors.findIndex(selector => heading.matches(selector)) - 1]); } }); // # create updater let cleanUp; const targets = id ? undefined : new WeakMap(); // map each anchor to its heading element const headings = []; const update = () => { if (!invalidation && !contents.isConnected) { return cleanUp?.(); } let newHeadings = [...root.querySelectorAll(selectors.join(", "))] .filter(h => [...registry].every(c => !c.contains(h))); filter && (newHeadings = newHeadings.filter(filter)); if ( // check whether the list is empty or identical to before !newHeadings.length || (headings.length == newHeadings.length && !headings.some((h, i) => newHeadings[i] !== h)) ) { return; } targets?.clear?.(); headings.splice(0, Infinity, ...newHeadings); let baseLevel = 0; let curLevel; let curList = document.createElement((order !== false && (baseLevel <= orderDepth)) ? "ol" : "ul"); // (order !== false) && (curList.dataset.depthA = baseLevel); (order !== false && order != 1) && (curList.start = order); for (let heading of headings) { // find the index of the first matching selector let nodeLevel = selectors.findIndex(selector => heading.matches(selector)) - 1; if (curLevel == undefined) { // The first header isn’t top-level. curLevel = baseLevel; while (nodeLevel > curLevel) { // indent curLevel++; let subList = document.createElement((order !== false && (curLevel <= orderDepth)) ? "ol" : "ul"); // (order !== false) && (curList.dataset.depthB = curLevel); (order !== false && order != 1) && (subList.start = order); curList.append(subList); curList = subList; } } else { while (curLevel < nodeLevel) { // indent curLevel++; let subList = document.createElement((order !== false && (curLevel <= orderDepth)) ? "ol" : "ul"); // (order !== false) && (curList.dataset.depthC = curLevel); (order !== false && order != 1) && (subList.start = order); curList.append(subList); curList = subList; } while (curLevel > nodeLevel) { // unindent curLevel--; curList = curList.parentElement ?? curList; } } let listItem = document.createElement("li"); let link = document.createElement("a"); link.append(...[...heading.childNodes].map(n => n.cloneNode(Infinity))); listItem.append(link); if (id) { let elmID = heading.id || (heading.id = DOM.uid().id); let loc = new URL(window.location); loc.search = ""; loc.hash = elmID; link.href = loc; } else { link.href = "#"; targets.set(link, heading); } modify?.call(undefined, {heading, link, listItem}); curList.append(listItem); } rootList.replaceChildren(...curList.childNodes); view && contents.dispatchEvent(new Event("input")); }; // # initialise MutationObserver const watcher = new MutationObserver(update); { let listener = id ? undefined : ["click", event => { let linked = targets.has(event.target); let target = linked ? event.target : event.target.closest("a"); if (target && (linked ||= targets.has(target))) { event.preventDefault(); targets.get(target).scrollIntoView(scrollOpts); } }, { passive: false }]; listener && contents.addEventListener(...listener); cleanUp = () => { cleanUp = undefined; registry.delete(contents); listener && contents.removeEventListener(...listener); watcher.disconnect(); headings.length = selectors.length = 0; }; } invalidation?.then(cleanUp); watcher.observe(root, { childList: true, subtree: true, characterData: true }); registry.add(contents); return contents; }; }49:[] 44:{"id":"24c4b2fc192b44fb","slug":"contents","title":"table of contents","thumbnail":"346a96cda89a613bfc2a88c087ce0efbe647464d97805bf9b6e4ca1096a58a1c","access_level":"public","create_time":"$D2022-06-07T23:22:48.792Z","update_time":"$D2022-06-19T22:24:35.342Z","view_time":null,"first_public_time":"$D2022-06-08T16:39:43.638Z","has_unpublished_edits":null,"fork":{"id":"9bed702f80a3797e","slug":"indented-toc","title":"Indented ToC","owner":{"id":"9bf3901b03c0276a","login":"nebrius","name":"Bryan Hughes"}},"stars":10,"starred":false,"owner":{"type":"team","id":"d2b7afa3a61febdf","login":"rmw4269","name":"Riley","avatar_url":"https://avatars-next.observableusercontent.com/839ad38e4ca0e32eaad7be29b5bc0c3a7f4304d5f91dd0f3642acf08015b6530","tier":"starter_2024","bio":"I enjoy spreadsheets and JavaScript way too much.","following":false},"version":736,"publish_version":736,"role":null,"authored":false,"authors":[{"type":"individual","id":"817e538440b46e8a","login":"rmw4269","name":"Riley","avatar_url":"https://avatars-next.observableusercontent.com/839ad38e4ca0e32eaad7be29b5bc0c3a7f4304d5f91dd0f3642acf08015b6530","tier":null,"bio":"I enjoy spreadsheets and JavaScript way too much.\n\ntrust://Riley.science!","following":false}],"members":[{"type":"individual","id":"817e538440b46e8a","login":"rmw4269","name":"Riley","avatar_url":"https://avatars-next.observableusercontent.com/839ad38e4ca0e32eaad7be29b5bc0c3a7f4304d5f91dd0f3642acf08015b6530","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":3,"collection":null,"type":"notebook","body":{"titling":"auto","title":"table of contents","cells":[{"id":0,"value":"$46","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":214,"value":"## usage\n\nimport {${ToC.name}} from \"@rmw4269/contents\"\n","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":228,"value":"### default\n\nYou can create the table of contents for a notebook with just ${ToC.name}().","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":30,"value":"ToC()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":241,"value":"### customizing header selectors\nIf you don’t like which header levels are included in the table of contents by default, you can customize which header levels to include. To find all of the headers, these CSS selectors are joined together with \", \"; then, each heading is given a hierarchy level by matching against the individual selectors in order (with the first match taking precedence). For example, a heading that matches the second selector is understood to be the second most important in the header hierarchy.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":284,"value":"ToC({\n headers: [\"h1\", \"h2\", \"p\"],\n filter: h => (h instanceof HTMLParagraphElement ? h.querySelector(\".hljs-variable\") : true),\n invalidation\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":287,"value":"### adding a title\nIf you would like to change the title, you can change it with the title option. This can be a string or a [Node](//developer.Mozilla.org/en-US/docs/Web/API/Node).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":291,"value":"ToC({\n title: \"table of contents\",\n invalidation\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":401,"value":"### skipping ~~some~~ sections\nIn some cases, you may want to omit a section. To skip a section, pass a string or array of strings to be omitted.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":400,"value":"ToC({ filter: \"API\", invalidation })","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":399,"value":"ToC({ filter: [\"API\", \"usage\"], order: 1, orderDepth: 1, invalidation })","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":695,"value":"ToC({ headers: \"li\", invalidation })","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":681,"value":"## issues\n\norder and orderDepth are not yet working, so please avoid using them. Enabling ID works in theory, but how Observable handles anchors pointing to elements by ID prevents this from functioning as it would in a native browser environment.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":332,"value":"$47","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":37,"value":"## implementation","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":127,"value":"$48","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W49","stdlib":"1"}} 45:"$44:body"