This is an automated email from the ASF dual-hosted git repository.
ashb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-site.git
The following commit(s) were added to refs/heads/main by this push:
new a6fd754482 Show grouped details blocks as tabs, like the Sphinx docs
(#1719)
a6fd754482 is described below
commit a6fd754482108b0b9425102bce09d379e91d3d76
Author: Ash Berlin-Taylor <[email protected]>
AuthorDate: Tue Nov 3 14:57:31 2026 +0000
Show grouped details blocks as tabs, like the Sphinx docs (#1719)
* Show grouped details blocks as tabs, like the Sphinx docs
Blog posts that show the same thing in several languages need the tabs
readers already know from the docs' sphinx-design tab sets. Markdown
content on this site has no tab syntax, and a Hugo shortcode would show
as raw text in GitHub's rich diff and need the {{% %}} form for Markdown
inside it.
Authors write ordinary <details> elements that share a `name`, so the
content works without JS: the browser shows the group as an exclusive
accordion where every tab can still be opened, and the script only adds
the tab strip on top once it loads. Tab sets that share a sync group
switch together. The choice lives under the same sessionStorage key and
URL parameter as sphinx-design, so a language picked in the docs on
airflow.apache.org carries over to the blog and back.
Switching a tab also resizes synced sets above it, which moves the
content the reader was looking at even though the scroll position stays
the same. We scroll by the height change so the clicked tab strip keeps
its place, which also covers browsers without scroll anchoring.
The tab strip follows the navbar's link colours and sliding underline
rather than the docs' palette, so tabs match the rest of the site.
The site loads the main bundle twice on some layouts, so enhancement
must be idempotent.
* Float the copy button and tighten padding on blog code blocks
Docsy only positions its copy button inside .td-content, but blog posts
render in .markdown-content, so the button took its own row above every
code block. The inline-code padding also matched the <code> inside each
<pre>, leaving a coloured strip before the first line.
With the button floating over the top padding, the bottom no longer
needs to match the top, and a full 1rem left a visible gap above the
horizontal scrollbar. The top keeps 1rem so the button doesn't cover
the first line.
---
landing-pages/site/assets/scss/_details-tabs.scss | 100 +++++++++++
.../site/assets/scss/_markdown-content.scss | 32 ++++
landing-pages/site/assets/scss/main-custom.scss | 5 +
landing-pages/src/index.js | 1 +
landing-pages/src/js/detailsTabs.js | 199 +++++++++++++++++++++
5 files changed, 337 insertions(+)
diff --git a/landing-pages/site/assets/scss/_details-tabs.scss
b/landing-pages/site/assets/scss/_details-tabs.scss
new file mode 100644
index 0000000000..585323f547
--- /dev/null
+++ b/landing-pages/site/assets/scss/_details-tabs.scss
@@ -0,0 +1,100 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+@import "colors";
+
+// Tab strip built by src/js/detailsTabs.js; colours and underline follow the
navbar links.
+.tab-set {
+ --tab-set-label: #{map-get($colors, brownish-grey)};
+ --tab-set-label-active: #{map-get($colors, greyish-brown)};
+ --tab-set-underline: #{map-get($colors, cerulean-blue)};
+ --tab-set-rule: #dedede;
+
+ margin: 1em 0 30px;
+
+ &__tabs {
+ display: flex;
+ flex-wrap: wrap;
+ }
+
+ &__tab {
+ position: relative;
+ padding: 1em 1.25em 0.5em;
+ border: 0;
+ border-radius: 0;
+ background: none;
+ color: var(--tab-set-label);
+ font: inherit;
+ font-size: 1rem;
+ font-weight: 700;
+ cursor: pointer;
+ transition: color 0.3s ease;
+
+ // Anchored right until hover/selection pins it left, so it grows in from
the left and leaves to the right.
+ &::after {
+ content: "";
+ position: absolute;
+ right: 0;
+ bottom: 0;
+ width: 0;
+ height: 2px;
+ background-color: var(--tab-set-underline);
+ transition: 0.2s ease-out;
+ }
+
+ &:hover,
+ &[aria-selected="true"] {
+ color: var(--tab-set-label-active);
+
+ &::after {
+ left: 0;
+ width: 100%;
+ }
+ }
+
+ &:focus-visible {
+ outline: 2px solid var(--tab-set-underline);
+ outline-offset: -2px;
+ }
+ }
+
+ > details {
+ padding: 0.75rem 0;
+ box-shadow: 0 -0.0625rem var(--tab-set-rule);
+
+ &:not([open]),
+ > summary {
+ display: none;
+ }
+
+ > summary + * {
+ margin-top: 0;
+ }
+
+ > :last-child {
+ margin-bottom: 0;
+ }
+ }
+}
+
+[data-bs-theme="dark"] .tab-set {
+ --tab-set-label: var(--bs-secondary-color);
+ --tab-set-label-active: var(--bs-emphasis-color);
+ --tab-set-rule: var(--bs-border-color);
+}
diff --git a/landing-pages/site/assets/scss/_markdown-content.scss
b/landing-pages/site/assets/scss/_markdown-content.scss
index 48ac96550e..6f9512d866 100644
--- a/landing-pages/site/assets/scss/_markdown-content.scss
+++ b/landing-pages/site/assets/scss/_markdown-content.scss
@@ -72,6 +72,38 @@
li {
color: #707070;
}
+
+ // Docsy floats its copy button only inside .td-content, which blog posts
don't use.
+ .highlight {
+ position: relative;
+ }
+
+ pre {
+ padding-bottom: 0.5rem;
+ }
+
+ button.td-click-to-copy {
+ --bs-btn-box-shadow: 0;
+
+ position: absolute;
+ top: 2px;
+ right: 4px;
+ padding: var(--bs-btn-padding-y) calc(var(--bs-btn-padding-x) / 2);
+ border-width: 0;
+ background-color: transparent;
+ background-image: none;
+ color: var(--bs-tertiary-color);
+
+ &:hover,
+ &:active {
+ color: var(--bs-secondary-color);
+ background-color: var(--bs-dark-bg-subtle);
+ }
+
+ &:active {
+ transform: translateY(2px);
+ }
+ }
}
[data-bs-theme="dark"] .markdown-content {
diff --git a/landing-pages/site/assets/scss/main-custom.scss
b/landing-pages/site/assets/scss/main-custom.scss
index 42c3d78393..abcc2b2e5b 100644
--- a/landing-pages/site/assets/scss/main-custom.scss
+++ b/landing-pages/site/assets/scss/main-custom.scss
@@ -24,6 +24,7 @@
@import "shared";
@import "typography";
@import "accordion";
+@import "details-tabs";
@import "buttons";
@import "ol-ul";
@import "list-boxes";
@@ -284,6 +285,10 @@ main li code,
background-color: #1a1f2e;
}
+.markdown-content pre > code {
+ padding: 0;
+}
+
/* Focus-visible enhancement for interactive elements */
:focus-visible {
outline: 3px solid #017cee;
diff --git a/landing-pages/src/index.js b/landing-pages/src/index.js
index 01c5b60c59..b1737b2fc7 100644
--- a/landing-pages/src/index.js
+++ b/landing-pages/src/index.js
@@ -26,6 +26,7 @@ import "./js/contentDrawer";
import "./js/progressTracking";
import "./js/rating";
import "./js/makeTableResponsive";
+import "./js/detailsTabs";
import "./js/versionSelector";
import "./js/scrollToTop";
diff --git a/landing-pages/src/js/detailsTabs.js
b/landing-pages/src/js/detailsTabs.js
new file mode 100644
index 0000000000..06f733c902
--- /dev/null
+++ b/landing-pages/src/js/detailsTabs.js
@@ -0,0 +1,199 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Turns runs of sibling `<details name="..." data-tab="...">` elements into a
tab set. Without JS they
+// remain an exclusive accordion. Tab sets sharing a `data-sync-group` switch
together, and the choice is
+// stored under the same sessionStorage key as sphinx-design so it carries
over to and from the docs.
+
+const TAB_SELECTOR = "details[data-tab]";
+const STORAGE_KEY_PREFIX = "sphinx-design-tab-id-";
+
+const readStoredTab = (group) => {
+ try {
+ return window.sessionStorage.getItem(STORAGE_KEY_PREFIX + group);
+ } catch {
+ return null;
+ }
+};
+
+const storeTab = (group, id) => {
+ try {
+ window.sessionStorage.setItem(STORAGE_KEY_PREFIX + group, id);
+ } catch {
+ // Storage can be unavailable (private mode, blocked site data); syncing
still works on this page.
+ }
+};
+
+const tabSetByPanel = new WeakMap();
+const tabSetsByGroup = new Map();
+
+class TabSet {
+ constructor(panels, index) {
+ this.panels = panels;
+ this.group = panels[0].dataset.syncGroup;
+
+ this.tablist = document.createElement("div");
+ this.tablist.className = "tab-set__tabs";
+ this.tablist.setAttribute("role", "tablist");
+ this.tablist.addEventListener("keydown", (event) => this.onKeydown(event));
+
+ const container = document.createElement("div");
+ container.className = "tab-set";
+ panels[0].before(container);
+ container.append(this.tablist, ...panels);
+
+ this.tabs = panels.map((panel, i) => this.createTab(panel, i,
`tab-set-${index}-${i}`));
+
+ const initial = panels.findIndex((panel) => panel.open);
+ this.select(initial === -1 ? 0 : initial);
+ }
+
+ createTab(panel, i, idPrefix) {
+ const tab = document.createElement("button");
+ tab.type = "button";
+ tab.className = "tab-set__tab";
+ tab.id = `${idPrefix}-tab`;
+ tab.setAttribute("role", "tab");
+
+ const summary = panel.querySelector(":scope > summary");
+ if (summary) {
+ tab.append(...summary.cloneNode(true).childNodes);
+ } else {
+ tab.textContent = panel.dataset.tab;
+ }
+
+ if (!panel.id) panel.id = `${idPrefix}-panel`;
+ panel.setAttribute("role", "tabpanel");
+ panel.setAttribute("aria-labelledby", tab.id);
+ tab.setAttribute("aria-controls", panel.id);
+
+ tab.addEventListener("click", () => this.activate(i));
+ // Browsers open closed details themselves (find-in-page, fragment
navigation), so follow along.
+ panel.addEventListener("toggle", () => {
+ if (panel.open) this.select(i);
+ });
+
+ tabSetByPanel.set(panel, {tabSet: this, index: i});
+ this.tablist.append(tab);
+ return tab;
+ }
+
+ select(index) {
+ this.panels.forEach((panel, i) => {
+ const selected = i === index;
+ panel.open = selected;
+ this.tabs[i].setAttribute("aria-selected", String(selected));
+ this.tabs[i].tabIndex = selected ? 0 : -1;
+ });
+ }
+
+ selectById(id) {
+ const index = this.panels.findIndex((panel) => panel.dataset.tab === id);
+ if (index !== -1) this.select(index);
+ }
+
+ activate(index) {
+ const anchorTop = this.tablist.getBoundingClientRect().top;
+ this.select(index);
+ if (this.group) {
+ const id = this.panels[index].dataset.tab;
+ tabSetsByGroup.get(this.group).forEach((tabSet) => {
+ if (tabSet !== this) tabSet.selectById(id);
+ });
+ storeTab(this.group, id);
+ }
+ // Synced sets above this one change height, so keep the strip the reader
clicked where it was.
+ const shift = this.tablist.getBoundingClientRect().top - anchorTop;
+ if (shift) window.scrollBy({top: shift, behavior: "instant"});
+ }
+
+ onKeydown(event) {
+ const current = this.tabs.indexOf(event.target);
+ if (current === -1) return;
+ const last = this.tabs.length - 1;
+ const next = {
+ ArrowRight: current === last ? 0 : current + 1,
+ ArrowLeft: current === 0 ? last : current - 1,
+ Home: 0,
+ End: last,
+ }[event.key];
+ if (next === undefined) return;
+ event.preventDefault();
+ this.activate(next);
+ this.tabs[next].focus();
+ }
+}
+
+const findTabSetRuns = () => {
+ const runs = [];
+ const runByLastPanel = new Map();
+ // Pages can include the bundle more than once, so skip panels a previous
run already enhanced.
+
document.querySelectorAll(`${TAB_SELECTOR}:not([role="tabpanel"])`).forEach((details)
=> {
+ const name = details.getAttribute("name");
+ const previous = details.previousElementSibling;
+ const run = runByLastPanel.get(previous);
+ if (name && run && previous.getAttribute("name") === name) {
+ run.push(details);
+ runByLastPanel.delete(previous);
+ runByLastPanel.set(details, run);
+ } else {
+ const newRun = [details];
+ runs.push(newRun);
+ runByLastPanel.set(details, newRun);
+ }
+ });
+ return runs;
+};
+
+const revealFragmentTarget = () => {
+ const id = decodeURIComponent(window.location.hash.slice(1));
+ const target = id && document.getElementById(id);
+ if (!target) return;
+ let revealed = false;
+ for (let panel = target.closest(TAB_SELECTOR); panel; panel =
panel.parentElement.closest(TAB_SELECTOR)) {
+ const owner = tabSetByPanel.get(panel);
+ if (owner && !panel.open) {
+ owner.tabSet.select(owner.index);
+ revealed = true;
+ }
+ }
+ if (revealed) target.scrollIntoView();
+};
+
+const initDetailsTabs = () => {
+ const urlParams = new URLSearchParams(window.location.search);
+
+ findTabSetRuns().forEach((panels, index) => {
+ const tabSet = new TabSet(panels, index);
+ if (!tabSet.group) return;
+ if (!tabSetsByGroup.has(tabSet.group)) {
+ tabSetsByGroup.set(tabSet.group, []);
+ const fromUrl = urlParams.get(tabSet.group);
+ if (fromUrl) storeTab(tabSet.group, fromUrl);
+ }
+ tabSetsByGroup.get(tabSet.group).push(tabSet);
+ const stored = readStoredTab(tabSet.group);
+ if (stored) tabSet.selectById(stored);
+ });
+
+ revealFragmentTarget();
+ window.addEventListener("hashchange", revealFragmentTarget);
+};
+
+initDetailsTabs();