Skip to content

docs: redesign documentation site UI #15214

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
devGregA wants to merge 7 commits into
base: bugfix
Choose a base branch
from
+1,353 −936
Open

docs: redesign documentation site UI #15214

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3177c6e
docs: redesign documentation site UI
devGregA Jul 10, 2026
8e0c27e
docs: fix active nav link contrast on navy header
devGregA Jul 10, 2026
a66e679
docs: remove baked-in canvas from dark-mode logo
devGregA Jul 10, 2026
54c60f8
stop os/pro switch flicker on page load
paulOsinski Jul 10, 2026
a6119e5
docs: let hero search button take its accessible name from visible text
paulOsinski Jul 10, 2026
bf7b4d3
docs: fix sidebar clipping and focus-ring artifacts
devGregA Jul 10, 2026
716bd86
docs: keep breadcrumbs on a single line
devGregA Jul 10, 2026
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
123 changes: 90 additions & 33 deletions docs/assets/js/custom.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,27 @@
// custom js


// version toggler
// Mobile navigation: the site sets doks.bootstrapJavascript = false, so no
// Bootstrap plugins load and the header's offcanvas toggles are dead markup.
// Importing the Offcanvas plugin evaluates its module, which registers the
// data-bs-toggle="offcanvas" click handling; the window reference keeps the
// import (and its side effects) from being tree-shaken.
import { Offcanvas } from 'bootstrap';

window.ddOffcanvas = Offcanvas;


// Edition toggler (Open Source / Pro)
//
// The sidebar renders both edition menus (.version-opensource / .version-pro).
// Which menu shows — and which segmented-control button reads as selected —
// is pure CSS keyed off html[data-dd-version] (see _custom.scss). An inline
// script in custom-head.html stamps that attribute from localStorage before
// first paint, so every page load renders the stored edition immediately with
// no hide-then-reveal flicker. This module only handles toggling: update the
// attribute, persist the choice, sync aria-checked for assistive tech.
(() => {
"use strict";

console.log("[VersionToggle] custom.js loaded");

// Asset-modelling landing pages per edition. The top nav is otherwise
// static, so a single URL can't be correct for both editions: we keep the
// "Model Your Assets" nav link in sync with the selected version, and —
Expand All @@ -28,30 +43,21 @@
};

const setVersion = (version) => {
console.log("[VersionToggle] Setting version to:", version);
// CSS shows the matching menu and highlights the matching button
document.documentElement.dataset.ddVersion = version;

document.querySelectorAll(".version-opensource, .version-pro").forEach(el => {
el.style.display = el.classList.contains(`version-${version}`) ? "block" : "none";
});

localStorage.setItem("version", version);
console.log("[VersionToggle] localStorage updated:", localStorage.getItem("version"));
try {
localStorage.setItem("version", version);
} catch (e) {
// Storage blocked (private browsing) — toggle still works this page
}

// Update dropdown
const selects = document.querySelectorAll("#version-select");
selects.forEach(sel => {
sel.value = version;
sel.dataset.version = version;
sel.style.visibility = "visible";
// aria-checked is for assistive tech only; visuals come from the
// html[data-dd-version] attribute above
document.querySelectorAll(".dd-version-seg button[data-version-value]").forEach(btn => {
btn.setAttribute("aria-checked", btn.dataset.versionValue === version ? "true" : "false");
});

// unhide sidebar after version is applied
const sidebar = document.querySelector(".docs-sidebar");
if (sidebar) {
sidebar.style.visibility = "visible";
console.log("[VersionToggle] Sidebar revealed");
}

// Edition-aware top nav: route "Model Your Assets" to the page that
// matches the selected version (see assetNavUrls above).
document.querySelectorAll("a.nav-link").forEach(link => {
Expand All @@ -62,19 +68,20 @@
};

const initVersionToggle = () => {
const storedVersion = localStorage.getItem("version") || "opensource";
console.log("[VersionToggle] Stored version:", storedVersion);
setVersion(storedVersion);
// custom-head.html already stamped the stored edition on <html> before

@accesslint accesslint Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

WCAG 2.4.2: Document is missing a <title> element.

Documents must have a <title> element to provide users with an overview of content.

Details

Page text: "// custom js // Mobile navigation: the site sets doks.bootstrapJavascript = false, so no // Bootstrap plugins load and the header's offcanvas toggles "

Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').

Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.

Page must have a mechanism to bypass repeated blocks of content.

Details

Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings

Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.

Best Practice: Page does not contain a level-one heading.

Page should contain a level-one heading.

Details

A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.

Best Practice: Page has no main landmark.

Page should have exactly one main landmark.

Details

The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.

WCAG 3.1.1: <html> element missing lang attribute.

The <html> element must have a lang attribute.

Details

Page text sample: "// custom js // Mobile navigation: the site sets doks.bootstrapJavascript = false, so no // Bootstrap plugins load and the header's offcanvas toggles are dead markup. // Importing the Offcanvas plugin"

Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).

@accesslint accesslint Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

WCAG 2.4.2: Document is missing a <title> element.

Documents must have a <title> element to provide users with an overview of content.

Details

Page text: "// custom js // Mobile navigation: the site sets doks.bootstrapJavascript = false, so no // Bootstrap plugins load and the header's offcanvas toggles "

Screen reader users rely on page titles to identify and navigate between tabs/windows. Add a descriptive <title> element in <head> that summarizes the page purpose. Keep titles unique across the site, placing specific content before the site name (e.g., 'Contact Us - Acme Corp').

Best Practice: Page has no mechanism to bypass repeated content. Add a <main> landmark or skip link.

Page must have a mechanism to bypass repeated blocks of content.

Details

Missing: no landmarks (<main>, <nav>, <header>, <footer>), no skip link, no headings

Keyboard users must be able to skip repetitive content like navigation. Provide a skip link at the top of the page that links to the main content (e.g., <a href="#main">Skip to main content</a>), or use a <main> landmark. Screen readers can jump directly to landmarks, so a properly marked-up <main> element satisfies this requirement.

Best Practice: Page does not contain a level-one heading.

Page should contain a level-one heading.

Details

A level-one heading (<h1> or role='heading' with aria-level='1') helps users understand the page topic and provides a landmark for screen reader navigation. Each page should have exactly one h1 that describes the main content, typically matching or similar to the page title.

Best Practice: Page has no main landmark.

Page should have exactly one main landmark.

Details

The main landmark contains the primary content of the page. Screen readers allow users to jump directly to main content. Use a single <main> element (or role='main') to wrap the central content, excluding headers, footers, and navigation.

WCAG 3.1.1: <html> element missing lang attribute.

The <html> element must have a lang attribute.

Details

Page text sample: "// custom js // Mobile navigation: the site sets doks.bootstrapJavascript = false, so no // Bootstrap plugins load and the header's offcanvas toggles are dead markup. // Importing the Offcanvas plugin"

Screen readers use the lang attribute to determine which language rules and pronunciation to use. Without it, content may be mispronounced. Set lang to the primary language of the page (e.g., lang='en' for English, lang='es' for Spanish).

// paint; re-applying it here syncs aria-checked and the nav link on
// freshly parsed (or dynamically replaced) markup.
setVersion(document.documentElement.dataset.ddVersion || "opensource");
};

// Delegated listener on body
document.body.addEventListener("change", (e) => {
if (e.target && e.target.id === "version-select") {
console.log("[VersionToggle] Dropdown changed to:", e.target.value);
setVersion(e.target.value);
// Delegated listener on body — catches every control instance
document.body.addEventListener("click", (e) => {
const btn = e.target.closest("button[data-version-value]");
if (btn) {
setVersion(btn.dataset.versionValue);
// Only on an explicit user toggle (not on load) follow the page to
// the matching edition when viewing an asset-modelling page.
switchAssetPageForVersion(e.target.value);
switchAssetPageForVersion(btn.dataset.versionValue);
}
});

Expand All @@ -91,6 +98,56 @@
})();


// Code block language labels — stamp the fence language onto each
// expressive-code frame's (empty) title span so CSS can render it in the
// header band via attr(data-lang). Frames whose fence "language" is really
// an editor artifact (paths, line ranges) get a generic "code" label.
(() => {
"use strict";

const CLEAN_LANG = /^[a-z0-9_+#.-]{1,16}$/i;

const init = () => {
document.querySelectorAll(".docs-content .expressive-code .frame").forEach(frame => {
const title = frame.querySelector(".header .title");
if (!title || title.textContent.trim() !== "" || title.dataset.lang) return;
const code = frame.querySelector("pre code[data-lang]");
let lang = code ? code.dataset.lang : "";
if (!lang || lang === "fallback" || !CLEAN_LANG.test(lang)) lang = "code";
title.dataset.lang = lang;
frame.classList.add("dd-has-lang");
});
};

if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", init);
} else {
init();
}
})();


// Homepage hero search field — forwards to the DocSearch modal
(() => {
"use strict";

const init = () => {
const trigger = document.getElementById("ddHomeSearch");
if (!trigger) return;
trigger.addEventListener("click", () => {
const btn = document.getElementsByClassName("DocSearch-Button")[0];
if (btn) btn.click();
});
};

if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", init);
} else {
init();
}
})();


// Scroll progress bar — shows reading progress on doc pages
(() => {
"use strict";
Expand Down
Loading
Loading