mkdocs-nested-tabs 0.1.0__py3-none-any.whl

mkdocs_nested_tabs/plugin.py

@@ -0,0 +1,45 @@
+import os
+
+from mkdocs.config import config_options
+from mkdocs.plugins import BasePlugin
+from mkdocs.structure.files import File
+
+STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
+ASSET_NAMES = ("nested-tabs.js", "nested-tabs.css")
+
+
+class NestedTabsPlugin(BasePlugin):
+    """Shows every navigation.tabs category with all its child pages at once,
+    instead of Material's hover-only dropdown. See README for background —
+    this fills a gap explicitly declined in squidfunk/mkdocs-material#4765.
+    """
+
+    config_scheme = (
+        # v0.1: static breakpoint/behavior, matching Material's own tabs
+        # breakpoint (76.234375em). Making these configurable needs the
+        # static JS/CSS to be templated per-build rather than served as
+        # fixed package assets — planned, not yet implemented.
+        ("enabled", config_options.Type(bool, default=True)),
+    )
+
+    def on_files(self, files, config):
+        if not self.config["enabled"]:
+            return files
+        # File(path, src_dir, dest_dir, ...) mirrors the same relative `path`
+        # under both src_dir and dest_dir — keeping the assets flat (no
+        # subfolder) in mkdocs_nested_tabs/static/ avoids any src/dest
+        # mismatch, at the cost of sitting at the built site's root rather
+        # than under its own assets/ subfolder. Confirmed working against
+        # tests/fixture_site (see tests/test_plugin.py).
+        for name in ASSET_NAMES:
+            files.append(
+                File(name, src_dir=STATIC_DIR, dest_dir=config["site_dir"], use_directory_urls=False)
+            )
+        return files
+
+    def on_config(self, config):
+        if not self.config["enabled"]:
+            return config
+        config["extra_javascript"] = ["nested-tabs.js", *config["extra_javascript"]]
+        config["extra_css"] = ["nested-tabs.css", *config["extra_css"]]
+        return config

mkdocs_nested_tabs/static/nested-tabs.css

@@ -0,0 +1,91 @@
+/* True desktop only (matches Material's own navigation.tabs breakpoint):
+   .mdx-nested-tabs replaces the native tab bar there — each category's name
+   is already its own column header in this row, so keeping both would show
+   every category name twice, stacked on top of itself. Below this width,
+   Material's native tabs (or the hamburger drawer) still apply unmodified. */
+@media screen and (min-width: 76.234375em) {
+  .md-tabs {
+    display: none;
+  }
+}
+
+/* .mdx-nested-tabs is inserted as a DOM child of .md-header, right after
+   .md-tabs (see nested-tabs.js) — so it's a genuine part of the header, not
+   a separate bar bolted on below: it rides along with .md-header's own
+   sticky positioning and background automatically. Transparent background
+   for the same reason .md-tabs is transparent: lets the header's own
+   background/artwork show through instead of drawing a second, visually
+   separate box. */
+.mdx-nested-tabs {
+  display: none;
+}
+
+@media screen and (min-width: 76.234375em) {
+  .mdx-nested-tabs {
+    display: block;
+    background-color: transparent;
+  }
+
+  .mdx-nested-tabs__list {
+    display: flex;
+    list-style: none;
+    margin: 0 0.2rem;
+    padding: 0.5rem 0;
+    gap: 1.4rem;
+  }
+
+  .mdx-nested-tabs__group {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+  }
+
+  .mdx-nested-tabs__label {
+    font-size: 0.64rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.03em;
+    /* Falls back to Material's own faded-foreground variable so this reads
+       reasonably on any palette out of the box; a consumer can override
+       --md-nested-tabs-label-color directly without touching this file. */
+    color: var(--md-nested-tabs-label-color, var(--md-default-fg-color--light));
+  }
+
+  /* A category with a third nesting level (see nested-tabs.js) renders as a
+     single link instead of a label + page list — needs its own hover/active
+     state, unlike the other groups' inert <span> labels. */
+  .mdx-nested-tabs__label--link {
+    text-decoration: none;
+  }
+
+  .mdx-nested-tabs__label--link:hover,
+  .mdx-nested-tabs__label--link:focus-visible {
+    color: var(--md-accent-fg-color);
+    text-decoration: underline;
+  }
+
+  .mdx-nested-tabs__pages {
+    display: flex;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    gap: 0.7rem;
+  }
+
+  .mdx-nested-tabs__link {
+    font-size: 0.7rem;
+    color: var(--md-nested-tabs-link-color, var(--md-default-fg-color));
+    text-decoration: none;
+  }
+
+  .mdx-nested-tabs__link:hover,
+  .mdx-nested-tabs__link:focus-visible {
+    color: var(--md-accent-fg-color);
+    text-decoration: underline;
+  }
+
+  .mdx-nested-tabs__link--active {
+    color: var(--md-accent-fg-color);
+    font-weight: 700;
+  }
+}

mkdocs_nested_tabs/static/nested-tabs.js

@@ -0,0 +1,142 @@
+(function () {
+  // Desktop-only nav row that replaces Material's native tab bar: every
+  // navigation.tabs category shown at once with all of its child pages
+  // listed underneath, instead of only being reachable via Material's
+  // hover-triggered tab dropdown (a gap explicitly declined upstream —
+  // see squidfunk/mkdocs-material#4765). Built by reading Material's own
+  // primary sidebar nav, which already contains the full site tree (every
+  // section, not just the active one — Material only flags the active
+  // top-level section with --section; every other one just gets --nested,
+  // regardless of which page you're on) rather than requiring a
+  // hand-maintained config list, so this stays in sync with mkdocs.yml's
+  // nav: block automatically.
+  //
+  // A category with a third nesting level (a sub-category with its own
+  // children, rather than a flat list of pages) doesn't fit the
+  // "category + pages" shape this row renders — those fall back to a
+  // single link, using the first leaf page found inside them as the
+  // target (usually an "index"/"All" overview page).
+
+  function buildNestedTabs() {
+    const primaryNav = document.querySelector(
+      '[data-md-component="sidebar"][data-md-type="navigation"] .md-nav--primary'
+    );
+    if (!primaryNav) return null;
+
+    const topList = primaryNav.querySelector(":scope > ul.md-nav__list");
+    if (!topList) return null;
+
+    const nav = document.createElement("nav");
+    nav.className = "mdx-nested-tabs";
+    nav.setAttribute("aria-label", "Categories");
+
+    // .md-tabs wraps its own list in a bare .md-grid div for the same
+    // centered max-width alignment as .md-header__inner (logo/title/search)
+    // — match that structure so this row lines up with the rest of the
+    // header instead of running edge-to-edge.
+    const grid = document.createElement("div");
+    grid.className = "md-grid mdx-nested-tabs__grid";
+
+    const list = document.createElement("ul");
+    list.className = "mdx-nested-tabs__list";
+
+    topList.querySelectorAll(":scope > li.md-nav__item--nested").forEach(function (section) {
+      const labelEl = section.querySelector(":scope > label.md-nav__link, :scope > a.md-nav__link");
+      const nestedNav = section.querySelector(":scope > nav.md-nav");
+      if (!labelEl || !nestedNav) return;
+
+      const categoryLabel = labelEl.querySelector(".md-ellipsis")
+        ? labelEl.querySelector(".md-ellipsis").textContent.trim()
+        : labelEl.textContent.trim();
+
+      const childItems = Array.from(nestedNav.querySelectorAll(":scope > ul.md-nav__list > li.md-nav__item"));
+      const pageLinks = [];
+      let flat = true;
+      for (const pageItem of childItems) {
+        // A real page item links directly to itself; a further-nested
+        // sub-category only has a label + its own nested nav, same shape
+        // as this top-level section.
+        const link = pageItem.querySelector(":scope > a.md-nav__link");
+        if (!link) {
+          flat = false;
+          break;
+        }
+        pageLinks.push(link);
+      }
+
+      const group = document.createElement("li");
+      group.className = "mdx-nested-tabs__group";
+
+      if (flat && pageLinks.length > 0) {
+        const label = document.createElement("span");
+        label.className = "mdx-nested-tabs__label";
+        label.textContent = categoryLabel;
+        group.appendChild(label);
+
+        const pages = document.createElement("ul");
+        pages.className = "mdx-nested-tabs__pages";
+        pageLinks.forEach(function (link) {
+          const item = document.createElement("li");
+          const a = document.createElement("a");
+          a.className = "mdx-nested-tabs__link";
+          a.href = link.getAttribute("href");
+          a.textContent = link.querySelector(".md-ellipsis")
+            ? link.querySelector(".md-ellipsis").textContent.trim()
+            : link.textContent.trim();
+          if (link.classList.contains("md-nav__link--active")) {
+            a.classList.add("mdx-nested-tabs__link--active");
+            a.setAttribute("aria-current", "page");
+          }
+          item.appendChild(a);
+          pages.appendChild(item);
+        });
+        group.appendChild(pages);
+      } else {
+        const overviewLink = nestedNav.querySelector(
+          ":scope > ul.md-nav__list > li.md-nav__item > a.md-nav__link"
+        );
+        if (!overviewLink) return;
+
+        const label = document.createElement("a");
+        label.className = "mdx-nested-tabs__label mdx-nested-tabs__label--link";
+        label.href = overviewLink.getAttribute("href");
+        label.textContent = categoryLabel;
+        if (overviewLink.classList.contains("md-nav__link--active")) {
+          label.classList.add("mdx-nested-tabs__link--active");
+          label.setAttribute("aria-current", "page");
+        }
+        group.appendChild(label);
+      }
+
+      list.appendChild(group);
+    });
+
+    if (!list.children.length) return null;
+
+    grid.appendChild(list);
+    nav.appendChild(grid);
+    return nav;
+  }
+
+  // .md-tabs lives inside .md-header (not below it, despite how it reads
+  // visually), so inserting right after it via insertAdjacentElement makes
+  // this row a header child too — it rides along with .md-header's own
+  // sticky positioning and decorative background for free, no separate
+  // sticky/offset math needed here.
+  function render() {
+    const existing = document.querySelector(".mdx-nested-tabs");
+    if (existing) existing.remove();
+
+    const nestedTabs = buildNestedTabs();
+    const tabs = document.querySelector(".md-tabs");
+    if (nestedTabs && tabs) {
+      tabs.insertAdjacentElement("afterend", nestedTabs);
+    }
+  }
+
+  if (window.document$) {
+    window.document$.subscribe(render);
+  } else {
+    document.addEventListener("DOMContentLoaded", render);
+  }
+})();

mkdocs_nested_tabs-0.1.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: mkdocs-nested-tabs
+Version: 0.1.0
+Summary: Display two levels of navigation.tabs instead of Material's hover-only dropdown.
+Author-email: Luka Sherman <lukawritecode@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/luka-sherman/mkdocs-nested-tabs
+Project-URL: Repository, https://github.com/luka-sherman/mkdocs-nested-tabs
+Project-URL: Issues, https://github.com/luka-sherman/mkdocs-nested-tabs/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: MkDocs
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.5
+Requires-Dist: mkdocs-material>=9.0
+Dynamic: license-file
+
+# mkdocs-nested-tabs
+
+Shows two hierarchy levels of `navigation.tabs` - one parent level, with it's children 
+displayed below it. An alternative to Material for MkDocs' native hover-triggered 
+tab dropdown (one category's children at a time). 
+
+## Status
+
+Early scaffold, ported and generalized from a working implementation. Not yet published.
+
+## Install
+
+```bash
+pip install mkdocs-nested-tabs   # not yet published
+```
+
+```yaml
+# mkdocs.yml
+theme:
+  name: material
+  features:
+    - navigation.tabs
+
+plugins:
+  - nested-tabs
+```
+
+Requires `navigation.tabs` to be enabled — this plugin replaces that
+feature's tab bar on desktop widths (≥76.234375em, matching Material's own
+breakpoint), it doesn't work alongside a site with tabs disabled.
+
+## How it works
+
+Reads Material's own primary sidebar nav at runtime (which already contains
+the full site tree — every category, not just the active one) and builds a
+second row inserted directly into `.md-header`, right after `.md-tabs`, so
+it inherits the header's own sticky positioning and background for free. A
+category with a third nesting level (a sub-category with its own children,
+rather than a flat list of pages) doesn't fit the "category + pages" shape
+this renders, so it falls back to a single link using the first leaf page
+found inside it.
+
+## Config
+
+```yaml
+plugins:
+  - nested-tabs:
+      enabled: true   # default
+```
+
+A configurable breakpoint and an option to keep Material's native tabs 
+alongside this row instead of hiding them. Both need the static JS/CSS to 
+be templated per-build rather than shipped as fixed package assets.
+
+## Theming
+
+Falls back to Material's own `--md-default-fg-color`/`--md-accent-fg-color`
+so it looks reasonable on any palette out of the box. Override via:
+
+```css
+:root {
+  --md-nested-tabs-label-color: ...;
+  --md-nested-tabs-link-color: ...;
+}
+```
+
+## Development
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e . mkdocs-material pytest
+python -m pytest tests/
+```
+
+Manual check: `cd tests/fixture_site && mkdocs serve`, then open the site
+and confirm the nested-tabs row renders at desktop width.

mkdocs_nested_tabs-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mkdocs_nested_tabs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocs_nested_tabs/plugin.py,sha256=Z0rAr5Epjc2GuhYKKqGHYcapDmtBBnufhbiNQd8gqOk,1903
+mkdocs_nested_tabs/static/nested-tabs.css,sha256=e_XiYSSD1ROefbGJkjZRgAROp6gtYXMGnIr0e2PTrpU,2742
+mkdocs_nested_tabs/static/nested-tabs.js,sha256=cNLAm0MxKRUTLg1Oiiuud6y5Vu5mtAcCAqkj5AcdoUs,5835
+mkdocs_nested_tabs-0.1.0.dist-info/licenses/LICENSE,sha256=8eSg7z3uZ_8PXMr30y4f3GlWv6ND5QUAIOB3eccrtc0,1069
+mkdocs_nested_tabs-0.1.0.dist-info/METADATA,sha256=42utYNzM8H8Ivr2t5EQWBQ6gdt-BCdBLQHhtMZbR_oQ,3068
+mkdocs_nested_tabs-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mkdocs_nested_tabs-0.1.0.dist-info/entry_points.txt,sha256=SxMM-nl2YLrXFkajtHvmf_hhUfX706IzuPuoCPPJU_k,74
+mkdocs_nested_tabs-0.1.0.dist-info/top_level.txt,sha256=OXfvOxPrKbR12BOZ1B_7OVZd6hBBgEgktFW1wTsHtms,19
+mkdocs_nested_tabs-0.1.0.dist-info/RECORD,,

mkdocs_nested_tabs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mkdocs_nested_tabs-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+nested-tabs = mkdocs_nested_tabs.plugin:NestedTabsPlugin

mkdocs_nested_tabs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luka Sherman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_nested_tabs-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_nested_tabs