Skip to content

docs: add tabbed navigation (Documentation / Release notes) #2718

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
claudiacodacy wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: add tabbed navigation (Documentation / Release notes) #2718

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4ba018f
docs: add tabbed navigation with full section restructuring
claudiacodacy Jul 31, 2026
d357cf0
docs: reduce tabbed navigation to Documentation and Release notes
claudiacodacy Jul 31, 2026
e79b7b4
docs: remove icons from Release notes and Special thanks
claudiacodacy Jul 31, 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
19 changes: 17 additions & 2 deletions docs/assets/javascripts/docs-theme.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,9 +158,24 @@ function initializeDocsTheme() {

if (drawerToggle.checked) {
window.setTimeout(function () {
var firstLink = drawer.querySelector(".md-nav__list a[href]");
// With navigation.tabs, every tab's subtree stays mounted in the
// drawer (Material slides the active one into view instead of
// removing the rest). Opening the drawer reliably leaves
// .md-sidebar__scrollwrap scrolled one panel-width to the right,
// hiding the active tab's own list off-screen. Force it back to
// the resting position before moving focus.
var scrollwrap = drawer.querySelector(".md-sidebar__scrollwrap");

@codacy-production codacy-production Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚪ LOW RISK

Nitpick: Use 'let' or 'const' instead of 'var' to maintain consistency with modern JavaScript practices and the existing code style in this file (specifically line 134).

if (scrollwrap) {
scrollwrap.scrollLeft = 0;
}

// The first link in document order can belong to a tab that
// isn't currently visible; focusing it without a scoped lookup
// would re-trigger the same off-screen scroll. Prefer the
// active tab's first link, and pass preventScroll as a backstop.
var firstLink = drawer.querySelector(".md-nav__item--active > .md-nav .md-nav__list a[href]") || drawer.querySelector(".md-nav__list a[href]");
if (firstLink) {
firstLink.focus();
firstLink.focus({ preventScroll: true });
}
}, 0);
} else {
Expand Down
272 changes: 137 additions & 135 deletions mkdocs.yml
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion theme/partials/nav-item.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
{% macro render_content(nav_item, ref, level = none) %}
{% set ref = ref or nav_item %}
{% set section_icons = config.extra.sidebar_icons or {} %}
{% if level == 1 and section_icons.get(nav_item.title) %}
{% if (level == 1 or (level == 2 and "navigation.tabs" in features)) and section_icons.get(nav_item.title) %}
{{ icon(section_icons.get(nav_item.title), "docs-nav-section-icon" ~ ("" if nav_item.children else " docs-nav-section-icon--standalone")) }}
{% elif nav_item.meta and nav_item.meta.icon %}
{% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %}
Expand Down
2 changes: 1 addition & 1 deletion theme/stylesheets/header.css
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion theme/stylesheets/layout.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.md-header__inner, .md-main__inner, .docs-footer__inner {
.md-header__inner, .md-main__inner, .docs-footer__inner, .md-tabs .md-grid {
box-sizing: border-box;
max-width: 90rem;
margin-inline: auto;
Expand Down
27 changes: 26 additions & 1 deletion theme/stylesheets/navigation.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,21 @@

.md-sidebar--primary .md-nav--primary > .md-nav__list { padding-inline: 1rem; }
.md-sidebar--primary .md-nav--primary .md-nav__link { margin-inline: 0; padding: .5rem; border-radius: var(--docs-radius-sm); }
.docs-nav-section-icon { flex: 0 0 .95rem; width: .95rem; height: .95rem; margin-right: .45rem; color: var(--docs-text-secondary); }
/* Material's stock ".md-nav__link svg { height: 1.3em }" outranks a plain
class selector on specificity, stretching every sidebar icon vertically.
Qualify with the element type to match and win on source order instead. */
svg.docs-nav-section-icon { flex: 0 0 .95rem; width: .95rem; height: .95rem; margin-right: .45rem; color: var(--docs-text-secondary); }

@codacy-production codacy-production Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚪ LOW RISK

Suggestion: This element-qualified selector (svg.docs-nav-section-icon) overrides default specificity to fix icon stretching. It is a valid solution, but be aware it will require updates if the icon implementation changes from an SVG to another element.

.docs-nav-section-icon--standalone { color: var(--docs-text-secondary); transition: color .12s ease; }
.md-nav__link--active .docs-nav-section-icon--standalone { color: var(--docs-link); }

.md-sidebar--primary .md-nav--primary > .md-nav__list > .md-nav__item { margin-block: .25rem; }
.md-nav--primary > .md-nav__list > .md-nav__item > .md-nav__link { margin-top: 0; }
/* Material's stock ".md-nav__link:focus { color: var(--md-accent-fg-color) }"
fires on plain :focus, not just :focus-visible — a link stays focused (and
blue) after a mouse click, not only real keyboard navigation, which reads
as a second "active" item sitting right under the actual one. Restrict the
accent color to genuine keyboard focus and non-active links. */
.md-nav__link:focus:not(:focus-visible):not(.md-nav__link--active) { color: var(--docs-text-secondary); }
.md-sidebar--primary .md-nav__link:is(:hover, :focus-visible) { color: var(--docs-text); background: var(--docs-bg-secondary); }
.md-sidebar--primary .md-nav__item .md-nav__link--active { background: var(--docs-bg-brand); }
.md-sidebar--primary .md-nav__item .md-nav__link--active:is(:hover, :focus-visible) { color: var(--docs-link); background: var(--docs-bg-brand); }
Expand All @@ -37,6 +46,13 @@
.md-nav--primary .md-nav__toggle ~ .md-nav > .md-nav__list { padding-left: 0; }

.md-nav--primary .md-nav .md-nav__toggle ~ .md-nav > .md-nav__list { padding-left: .8rem; }

/* Align level-3 pages (the ones revealed when you expand a tab's top-level
group) with that group's own text, not just Material's default indent.
Scoped to exactly this depth via a full child-selector chain so it
doesn't cascade into deeper levels (FAQ subcategories, release-notes
years), which should keep the smaller default indent. */
.md-nav--primary > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list { padding-left: 1.8rem; }
.md-sidebar__scrollwrap { overscroll-behavior: contain; scrollbar-color: auto !important; scrollbar-gutter: auto; scrollbar-width: auto !important; }
.md-sidebar__scrollwrap::-webkit-scrollbar, .md-sidebar__scrollwrap::-webkit-scrollbar-thumb, .md-sidebar__scrollwrap::-webkit-scrollbar-track { width: auto; height: auto; background: initial !important; }
.md-sidebar__scrollwrap::-webkit-scrollbar-thumb:hover { background: initial !important; }
Expand All @@ -62,3 +78,12 @@
.md-path__item + .md-path__item::before { display: none; }
.docs-ionicon--breadcrumb { flex: 0 0 .8rem; width: .8rem; height: .8rem; margin: 0 .2rem; color: var(--docs-text-tertiary); }
.md-path__item:first-child .docs-ionicon--breadcrumb { display: none; }

.md-tabs { border-bottom: 1px solid var(--docs-border); background: transparent; }
.md-tabs__list { gap: .25rem; margin-inline: 0; }
.md-tabs__item { height: 2.75rem; padding-inline: .5rem; }
.md-tabs__item:first-child { padding-left: 0; }
.md-tabs__item:last-child { padding-right: 0; }
.md-tabs__link { display: flex; height: 100%; align-items: center; margin-top: 0; padding: 0 .1rem; border-bottom: 2px solid transparent; color: var(--docs-text-secondary); font-size: .8125rem; font-weight: 500; opacity: 1; transition: color .12s ease, border-color .12s ease; }
.md-tabs__link:hover { color: var(--docs-text); }
.md-tabs__item--active .md-tabs__link { border-bottom-color: var(--docs-link); color: var(--docs-link); font-weight: 600; opacity: 1; }
25 changes: 25 additions & 0 deletions theme/stylesheets/responsive.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,31 @@
.md-header__button[data-drawer-trigger] { display: none; }
.md-nav--primary > .md-nav__title { display: none; }

/* The active tab's own name already shows in the .md-tabs bar above, so
drop the redundant repeated label at the top of its sidebar (mobile
still needs it — it's the only place a tab name appears there). */
.md-nav--primary > .md-nav__list > .md-nav__item > .md-nav__link { display: none; }

@codacy-production codacy-production Bot Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 MEDIUM RISK

This selector and the one on line 45 should be scoped to .md-nav--lifted (e.g., .md-nav--lifted > .md-nav__list ...). This ensures that tab labels are only hidden and top-level sections are only restyled when tabbed navigation is active. Without this, disabling tabs in the configuration would break the standard sidebar layout.


/* Material's own lifted-nav rule pulls each tab's level-2 list left by
.6rem (it assumes the now-hidden tab-name label above it needs the
extra room). With that label gone, the negative margin instead shifts
level-2 icons past the sidebar's left edge, clipping them. */
[dir="ltr"] .md-nav--lifted > .md-nav__list > .md-nav__item > .md-nav:not(.md-nav--secondary) { margin-left: 0; }
[dir="rtl"] .md-nav--lifted > .md-nav__list > .md-nav__item > .md-nav:not(.md-nav--secondary) { margin-right: 0; }

/* Give each tab's top-level items (e.g. "Quality", "Configuring your
repositories", but also flat pages like "AI" or "Documentation home")
the same small/bold/uppercase treatment the tab-name label above used
to have, now that it's the highest-level heading actually visible in
the sidebar. Applied uniformly regardless of whether the item has
children, so flat pages don't look out of place next to groups. */
.md-nav--primary > .md-nav__list > .md-nav__item > .md-nav > .md-nav__list > .md-nav__item > .md-nav__link {
font-size: .75rem;
font-weight: 700;
letter-spacing: .025em;
text-transform: uppercase;
}

.md-path { margin-top: 1.25rem; margin-right: 1.2rem; margin-left: 1.2rem; }
.md-sidebar--primary { padding-top: .75rem; }
.md-sidebar--secondary { padding-top: .75rem; }
Expand Down
Loading