Runtime sidebar

[UserNameUnavailableIsUnavailable]

Currently, the website's sidebar is generated at compile time, requiring a re-compilation whenever new files are added. Initially, I managed this by maintaining separate _sidebar.yml files within each subfolder and including them in _quarto.yml with metadata-files. However, as the project has grown bigger, I have adopted a different approach—including a sidebar-generating JavaScript script within _quarto.yml, which dynamically fetches sidebar.json contained in each subfolder at runtime. This eliminates the need to recompile the project when I want to add new content to the website.

While this method has been effective (you may see the effect here https://blog.macrohard.fun/CSOL-Utilities/index.html, working exactly the same). However, the current implementation of makeRuntimeSidebarItems is quite tedious, inserting sidebar items into the webpage one by one. Moreover, some CSS attributes for sidebar, such as "data-bs-toggle", may become deprecated in future versions or replaced with new styling conventions, leading to potential maintenance challenges.

So, I wonder if there could be an API or some other mechanisms to handle runtime sidebar generation, Such an API would enhance flexibility and stability.

I truly appreciate the effort put into this project. Thank you for considering this suggestion!

[mcanouil]

Accessibility: For better accessibility, please ensure your screenshots have proper alternative text. Thanks.

[UserNameUnavailableIsUnavailable]

Ok, I will describe my design in detail.

Firstly, I defined a json format for runtime sidebar, the json file defines 3 types of nodes: root, section, and document:

• root: the root node of the sidebar;
• section: a sidebar may contain several sections (sections can be nested);
• document: an ordinary html file.

Each node has a title (which is title shown in the sidebar) and an href (refers to the html file), for root and section, an extra children array is used to store items they contain. So, I get a json file like this:

{
    "type": "root",
    "title": "Root",
    "href": "/root/index.html",
    "children": [
        {
            "type": "document",
            "title": "⤴︎", // back to last subdir
            "href": "/root/../index.html"
        },
        {
            "type": "document",
            "title": "Root",
            "href": "/root/index.html",
            "active": true
        },
        {
            "type": "document",
            "title": "Section 01",
            "href": "/root/section_01/index.html"
            "children": [ /* ... */ ]
        },
    ]
}

The reason why section has href is to achieve the effect that when clicking on an section in the sidebar, its index file can be loaded.

For sections, its contents and sidebar.json are stored in the section's sub-directory, so, a section in a directory is a root in its own sub-directory. So, for Section 01 in the above example, it has the following json file:

{
    "type": "root",
    "title": "Section 01",
    "href": "/root/section_01/index.html",
    "children": [
        {
            "type": "document",
            "title": "⤴︎",
            "href": "/root/section_01/../index.html"
        },
        {
            "type": "document",
            "title": "Section 01",
            "href": "/root/section_01/index.html",
            "active": true
        },
        {
            "type": "document",
            "title": "Document-1-1",
            "href": "/root/section_01/document-1-1.html"
        }
    ]
}

Then, I wrote a tedious JS script that fetches & parses the above json files. Since I found creating a sidebar from scratch would bring me a lot of bugs, so for now, I first find an existing quarto-sidebar element, if it exists, the script will parse and generate a new sidebar navigation, then replace the original one contained in the document.

/// Extract the containing directory's URL. E.g., for https://example.com/foo/bar.txt, returns https://example.com/foo
/// @param `url` a URL
function getContainingDirectory(url) {
    // url: https://example.com/path/to/file.txt
    let origin = url.origin // https://example.com
    let pathname = url.pathname // /path/to/file.txt
    let lastSlashIndex = pathname.lastIndexOf("/")
    let directoryPath = pathname.slice(0, lastSlashIndex + 1) // /path/to/
    return new URL(`${origin}${directoryPath}`) // https://example.com/path/to/
}

/// Make an element (this is copied from quarto's source code)
/// @param `name` element name, e.g., `"div"`
/// @param `attr` list of attributes
/// @param `doc` DOM object, i.e., `document`
function makeEl(name, attr, doc) {
    const el = doc.createElement(name);
    if (attr.id) {
        el.id = attr.id;
    }
    for (const cls of attr.classes || []) {
        el.classList.add(cls);
    }
    const attribs = attr.attributes || {};
    for (const key of Object.keys(attribs)) {
        el.setAttribute(key, attribs[key]);
    }
    return el;
}

let sectionId = 1 // section id starts from 1

/// Recursively make runtime sidebars, store them in a <ul>.
/// @param `list` a json node
/// @param `level` levels of indentation, e.g., for `root`, `level` = 1, for `root`'s children, `level` = 2, for `section`'s children, `level` = 1 + `section`'s level
/// @param `doc` always set to `document`
/// @param `baseUrl` the base URL to be inserted before the `href` property
function makeRuntimeSidebarItems(list, level, doc, baseUrl) {
    let ul = undefined
    if (!list) { return } // run until list becomes null
// here comes the dirty work, creating sidebar items accordingly
// honestly, I don't quite understand the meaning of some css classes, so I just keep the original sidebar structure here
    let attr = { classes: ["list-unstyled"] }
    if (list.type === "root") {
        attr.classes.push("mt-1")
    } else {
        if (list.type === "section") {
            attr.classes.push("sidebar-section")
        }
        if (list.collapse) {
            attr.classes.push("collapse")
        }
        attr.classes.push(`depth${level}`)
        attr.classes.push("show")
    }
    ul = makeEl("ul", attr, doc)
    list.children.forEach(e => {
        if (e.type === "section") { // section
            let li = makeEl("li", { classes: ["sidebar-item", "sidebar-item-section"] }, doc)
            let div = makeEl("div", { classes: ["sidebar-item-container"] }, doc)
            let url = new URL(e.href, baseUrl)
            let a1 = makeEl("a", { classes: ["sidebar-item-text", "sidebar-link"], attributes: { "href": url.href } }, doc)
            a1.innerHTML = `<span class="menu-text">${e.title}</span>`
            let a2 = makeEl("a", { classes: ["sidebar-item-toggle", "text-start"], attributes: { "href": url.href } }, doc)
            a2.setAttribute("data-bs-toggle", "collapse")
            a2.setAttribute("data-bs-target", `#quarto-sidebar-section-${sectionId}`)
            a2.setAttribute("role", "navigation")
            a2.setAttribute("aria-expanded", e.collapse ? "false" : "true")
            a2.innerHTML = `<i class="bi bi-chevron-right ms-2"></i>`
            if (window.location.href === url.href) {
                a1.classList.add("active")
            }
            div.appendChild(a1)
            div.appendChild(a2)
            li.appendChild(div)
            let subul = makeRuntimeSidebarItems(e, level + 1, doc, baseUrl)
            if (subul) {
                li.appendChild(subul)
            }
            subul.id = `quarto-sidebar-section-${sectionId}`
            subul.classList.add("collapse")
            sectionId++
            ul.appendChild(li)
        } else if (e.type === "document") { // document
            let li = makeEl("li", { classes: ["sidebar-item"] }, doc)
            let div = makeEl("div", { classes: ["sidebar-item-container"] }, doc)
            let url = new URL(e.href, baseUrl)
            let a = makeEl("a", { classes: ["sidebar-item-text", "sidebar-link"], attributes: { "href": url.href } }, doc)
            if (window.location.href === url.href) {
                a.classList.add("active")
            }
            a.innerHTML = `<span class="menu-text">${e.title}</span>`
            div.appendChild(a)
            li.appendChild(div)
            ul.appendChild(li)
        }
    })
    return ul
}

/// The driver function that makes sidebars for the current page.
async function makeRuntimeSidebar() {
    // check if there already exists a quarto-sidebar, since I find many bugs when I tried to create such a sidebar from scrach
    // find an existing sidebar, then replacing some of its contents is easier
    let quartoSidebar = document.getElementById("quarto-sidebar")
    if (!quartoSidebar) {
        return
    }
    let runtimeSidebar
    // this is to check if a RuntimeSidebar is needed (this property is added in the lua filter)
    let meta = document.querySelector("meta[name=RuntimeSidebar]") // this is to check if a RuntimeSidebar is needed (this property is added in the lua filter)
    if (!meta) {
        runtimeSidebar = true
    } else {
        runtimeSidebar = meta.getAttribute("content") === "true" ? true : false
    }
    if (!runtimeSidebar) { return }
    let documentUrl = new URL(window.location.href) // https://example.com/path/to/file.txt
    let fallbackSidebarUrl = new URL("sidebar.json", documentUrl.origin) // https://example.com/path/to/sidebar.json
    let containingDirectory = getContainingDirectory(documentUrl) // https://example.com/path/to/
    let sidebar = "sidebar.json"
    let sidebarUrl = new URL(sidebar, containingDirectory) // https://example.com/path/to/sidebar.json
    let sidebarJson = undefined
    let response = await fetch(sidebarUrl) // fetch sidebar.json
    if (!response.ok) {
        return
    }
        await response.json().then((sidebarJson) => {
        console.log(sidebarJson)
        let sidebarNav = makeEl("nav", { id: "quarto-sidebar", classes: ["sidebar", "collapse", "collapse-horizontal", "quarto-sidebar-collapse-item", "sidebar-navigation", "docked", "overflow-auto",] }, document)
        let sidebarMenuContainer = makeEl("div", { classes: ["sidebar-menu-container",] }, document)
        let ul = makeRuntimeSidebarItems(sidebarJson, 0, document, documentUrl.origin)
        if (ul) {
            sidebarMenuContainer.appendChild(ul)
        }
        sidebarNav.appendChild(sidebarMenuContainer)
        console.log(quartoSidebar)
        sidebarNav.style = quartoSidebar.style
        quartoSidebar.replaceWith(sidebarNav)
        console.log(sidebarNav)
        console.log(document.getElementById("quarto-content")) 
    })
}

// make sidebar
makeRuntimeSidebar()

For each directory, if RuntimeSidebar is set, a sidebar.json is guaranteed to be found. For situations like this:

TheOnlyRoot
    |—index.html
    |—SectionA
        |—index.html
        |—a.html
    |—SectionB
        |—index.html
        |—b.html

Since there are only a few files here, I want all sections and its contents to share this structure, rather than, e.g., when I open a.html, by default SectionA will become the root, so you will see this:

|—SectionA
    |—index.html
    |—a.html

My workaround here is to create a symlink in SectionA, referring to the sidebar.json located at TheOnlyRoot.

By the way, I have another python script that generates the json file and do the symlinking jobs for me automatically. I can create a minimal standalone project to demonstrate all this if you want more details.