mkdocs-audience-toggle 0.1.0__py3-none-any.whl

mkdocs_audience_toggle/plugin.py

@@ -0,0 +1,122 @@
+import json
+import os
+
+from mkdocs.config import config_options
+from mkdocs.plugins import BasePlugin
+from mkdocs.utils import copy_file, log
+
+STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
+JS_FILENAME = "audience_toggle.js"
+CSS_FILENAME = "audience_toggle.css"
+ASSET_PREFIX = "assets/audience_toggle"
+CONFIG_SCRIPT_ID = "fcm-config"
+
+DEFAULTS = {
+    "storage_key": "fcm-mode",
+    "query_param": None,
+    "insert_selector": '[data-md-component="palette"]',
+    "hide_toc_entries": True,
+    "wrapper_class": None,
+    "attribute": "data-fcm-hide",
+}
+
+
+class AudienceTogglePlugin(BasePlugin):
+    config_scheme = (
+        ("modes", config_options.Type(list, default=[])),
+        ("storage_key", config_options.Type(str, default=DEFAULTS["storage_key"])),
+        ("query_param", config_options.Type(str, default="")),
+        ("insert_selector", config_options.Type(str, default=DEFAULTS["insert_selector"])),
+        ("hide_toc_entries", config_options.Type(bool, default=True)),
+        ("wrapper_class", config_options.Type(list, default=[])),
+        ("attribute", config_options.Type(str, default=DEFAULTS["attribute"])),
+        ("aria_label", config_options.Type(str, default="Content mode")),
+        ("collapse_labels", config_options.Type(bool, default=False)),
+        ("show_toast", config_options.Type(bool, default=True)),
+    )
+
+    def on_config(self, config):
+        modes = self.config.get("modes") or []
+        if not modes:
+            log.warning(
+                "audience_toggle: no 'modes' configured in mkdocs.yml, so the "
+                "toggle will not be inserted."
+            )
+        normalized = []
+        seen_names = set()
+        default_name = None
+        for i, raw in enumerate(modes):
+            if not isinstance(raw, dict) or "name" not in raw:
+                raise ValueError(
+                    "audience_toggle: each entry under 'modes' must be a "
+                    "mapping with at least a 'name' key (got %r)" % (raw,)
+                )
+            name = str(raw["name"])
+            if name in seen_names:
+                raise ValueError(
+                    "audience_toggle: duplicate mode name %r in 'modes'" % name
+                )
+            seen_names.add(name)
+            entry = {
+                "name": name,
+                "label": str(raw.get("label", name.title())),
+                "icon": raw.get("icon"),
+                "description": raw.get("description"),
+                "announcement": raw.get("announcement"),
+            }
+            if raw.get("default"):
+                if default_name is not None:
+                    raise ValueError(
+                        "audience_toggle: more than one mode marked default: true"
+                    )
+                default_name = name
+            normalized.append(entry)
+
+        if normalized and default_name is None:
+            default_name = normalized[0]["name"]
+
+        self._runtime_config = {
+            "modes": normalized,
+            "defaultMode": default_name,
+            "storageKey": self.config["storage_key"],
+            "queryParam": self.config["query_param"] or None,
+            "insertSelector": self.config["insert_selector"],
+            "hideTocEntries": self.config["hide_toc_entries"],
+            "wrapperClasses": list(self.config["wrapper_class"] or []),
+            "attribute": self.config["attribute"],
+            "ariaLabel": self.config["aria_label"],
+            "collapseLabels": self.config["collapse_labels"],
+            "showToast": self.config["show_toast"],
+        }
+
+        extra_css = list(config.get("extra_css", []))
+        extra_js = list(config.get("extra_javascript", []))
+        css_uri = f"{ASSET_PREFIX}/{CSS_FILENAME}"
+        js_uri = f"{ASSET_PREFIX}/{JS_FILENAME}"
+        if css_uri not in extra_css:
+            extra_css.append(css_uri)
+        if js_uri not in extra_js:
+            extra_js.append(js_uri)
+        config["extra_css"] = extra_css
+        config["extra_javascript"] = extra_js
+
+        return config
+
+    def on_post_build(self, config):
+        for filename in (JS_FILENAME, CSS_FILENAME):
+            src_path = os.path.join(STATIC_DIR, filename)
+            dest_path = os.path.join(config["site_dir"], ASSET_PREFIX, filename)
+            copy_file(src_path, dest_path)
+
+    def on_post_page(self, output, page, config):
+        if not getattr(self, "_runtime_config", None) or not self._runtime_config["modes"]:
+            return output
+        script = (
+            f'<script id="{CONFIG_SCRIPT_ID}" type="application/json">'
+            f"{json.dumps(self._runtime_config)}"
+            f"</script>"
+        )
+        marker = "</body>"
+        if marker in output:
+            return output.replace(marker, script + marker, 1)
+        return output + script

mkdocs_audience_toggle/static/audience_toggle.css

@@ -0,0 +1,133 @@
+/* mkdocs-audience-toggle
+
+   Custom properties (set on #fcm-toggle or a parent such as :root):
+     --fcm-accent       border and highlight color (default: currentColor)
+     --fcm-track-bg     toggle background (default: transparent)
+     --fcm-active-fg    text color of the active option (default: Canvas)
+     --fcm-radius       corner radius of the toggle and highlight
+     --fcm-height       toggle height
+     --fcm-font-size    label font size
+     --fcm-icon-size    icon size */
+
+.fcm-toggle {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  height: var(--fcm-height, 1.2rem);
+  border: 0.05rem solid var(--fcm-accent, currentColor);
+  border-radius: var(--fcm-radius, 1rem);
+  overflow: hidden;
+  background-color: var(--fcm-track-bg, transparent);
+}
+
+/* left and width are set by the script to match the active option. */
+.fcm-highlight {
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
+  border-radius: var(--fcm-radius, 1rem);
+  background-color: var(--fcm-accent, currentColor);
+  transition: left 0.2s ease, width 0.2s ease;
+}
+
+.fcm-option {
+  position: relative;
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 1;
+  padding: 0 0.5rem;
+  border: none;
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-size: var(--fcm-font-size, 0.6rem);
+  font-weight: 700;
+  letter-spacing: 0.02em;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.fcm-option[aria-pressed="true"] {
+  color: var(--fcm-active-fg, Canvas);
+}
+
+/* The icon is a mask over currentColor so it matches the label color. */
+.fcm-option--icon::before {
+  content: "";
+  display: inline-block;
+  width: var(--fcm-icon-size, 0.7rem);
+  height: var(--fcm-icon-size, 0.7rem);
+  margin-right: 0.3rem;
+  flex: none;
+  background-color: currentColor;
+  -webkit-mask-image: var(--fcm-icon);
+  mask-image: var(--fcm-icon);
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-size: contain;
+  mask-size: contain;
+  -webkit-mask-position: center;
+  mask-position: center;
+}
+
+@media (max-width: 45em) {
+  .fcm-toggle[data-collapse-labels] .fcm-option--icon::before {
+    margin-right: 0;
+  }
+
+  .fcm-toggle[data-collapse-labels] .fcm-label {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+  }
+}
+
+/* Material header on narrow screens: if the toggle doesn't fit next to the
+   title, the script adds .fcm-toggle--own-row, which moves it after the other
+   header buttons so it gets a row to itself. */
+@media (max-width: 45em) {
+  .md-header__inner:has(> #fcm-toggle) {
+    flex-wrap: wrap;
+    row-gap: 0.2rem;
+  }
+
+  .md-header__inner > #fcm-toggle.fcm-toggle--own-row {
+    order: 1;
+    margin: 0.1rem auto 0.2rem;
+  }
+}
+
+.fcm-toast {
+  position: fixed;
+  left: 50%;
+  z-index: 10;
+  padding: 0.5rem 0.9rem;
+  border-radius: 0.4rem;
+  background-color: var(--fcm-accent, currentColor);
+  color: var(--fcm-active-fg, Canvas);
+  font-size: 0.7rem;
+  font-weight: 700;
+  white-space: nowrap;
+  opacity: 0;
+  pointer-events: none;
+  transform: translate(-50%, -0.3rem);
+  transition: opacity 0.2s ease, transform 0.2s ease;
+}
+
+.fcm-toast--visible {
+  opacity: 1;
+  transform: translate(-50%, 0);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .fcm-highlight,
+  .fcm-toast {
+    transition: none;
+  }
+}

mkdocs_audience_toggle/static/audience_toggle.js

@@ -0,0 +1,332 @@
+(function () {
+  "use strict";
+
+  var CONFIG_SCRIPT_ID = "fcm-config";
+
+  function readConfig() {
+    var el = document.getElementById(CONFIG_SCRIPT_ID);
+    if (!el) return null;
+    try {
+      var config = JSON.parse(el.textContent);
+      if (!config.modes || !config.modes.length) return null;
+      return config;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // A heading hides its whole section: every following sibling up to the next
+  // heading of the same or higher level.
+  function setElementHidden(el, hidden, config) {
+    el.style.display = hidden ? "none" : "";
+
+    if (/^H[1-6]$/.test(el.tagName)) {
+      var level = Number(el.tagName[1]);
+      var sib = el.nextElementSibling;
+      while (sib && !(/^H[1-6]$/.test(sib.tagName) && Number(sib.tagName[1]) <= level)) {
+        sib.style.display = hidden ? "none" : "";
+        sib = sib.nextElementSibling;
+      }
+
+      var wrapper = el.parentElement;
+      if (
+        wrapper &&
+        config.wrapperClasses &&
+        config.wrapperClasses.length &&
+        wrapper.firstElementChild === el &&
+        config.wrapperClasses.some(function (cls) {
+          return wrapper.classList.contains(cls);
+        })
+      ) {
+        wrapper.style.display = hidden ? "none" : "";
+      }
+
+      if (config.hideTocEntries && el.id) {
+        setTocEntryHidden(el.id, hidden);
+      }
+    }
+  }
+
+  // Material can render the same TOC link more than once (primary nav and
+  // secondary sidebar), so hide every match.
+  function setTocEntryHidden(id, hidden) {
+    document.querySelectorAll('a.md-nav__link[href$="#' + id + '"]').forEach(function (link) {
+      var item = link.closest(".md-nav__item");
+      if (item) item.style.display = hidden ? "none" : "";
+    });
+  }
+
+  function applyContentVisibility(mode, config) {
+    var selector = "[" + config.attribute + "]";
+    document.querySelectorAll(selector).forEach(function (el) {
+      var tokens = (el.getAttribute(config.attribute) || "").split(/\s+/).filter(Boolean);
+      setElementHidden(el, tokens.indexOf(mode) !== -1, config);
+    });
+  }
+
+  function applyState(container, mode, config) {
+    var previousMode = container.dataset.active || null;
+
+    document.documentElement.setAttribute("data-fcm-mode", mode);
+    applyContentVisibility(mode, config);
+
+    container.dataset.active = mode;
+    var activeOption = null;
+    container.querySelectorAll(".fcm-option").forEach(function (option) {
+      var isActive = option.dataset.name === mode;
+      option.setAttribute("aria-pressed", String(isActive));
+      if (isActive) activeOption = option;
+    });
+    positionHighlight(container, activeOption);
+
+    if (previousMode !== mode) {
+      document.dispatchEvent(
+        new CustomEvent("fcm:modechange", { detail: { mode: mode, previousMode: previousMode } })
+      );
+    }
+  }
+
+  // Options size to their labels, so the highlight is measured from the active
+  // option rather than set to an equal share of the track.
+  function positionHighlight(container, activeOption) {
+    var highlight = container.querySelector(".fcm-highlight");
+    if (!highlight || !activeOption) return;
+    highlight.style.left = activeOption.offsetLeft + "px";
+    highlight.style.width = activeOption.offsetWidth + "px";
+  }
+
+  // Material header only: if the toggle wrapped below the title, give it a row
+  // to itself (see .fcm-toggle--own-row in the CSS). Measured with the class
+  // off, so the toggle keeps its place whenever it fits.
+  function updateHeaderRow(container) {
+    var inner = container.parentElement;
+    if (!inner || !inner.classList.contains("md-header__inner")) return;
+    var title = inner.querySelector(".md-header__title");
+    if (!title) return;
+
+    container.classList.remove("fcm-toggle--own-row");
+    var wrapped = container.getBoundingClientRect().top >= title.getBoundingClientRect().bottom - 1;
+    container.classList.toggle("fcm-toggle--own-row", wrapped);
+  }
+
+  function refreshLayout() {
+    var container = document.getElementById("fcm-toggle");
+    if (!container) return;
+    updateHeaderRow(container);
+    positionHighlight(container, container.querySelector('.fcm-option[aria-pressed="true"]'));
+  }
+
+  var toastTimer = null;
+  function showToast(mode, config) {
+    if (!config.showToast) return;
+    var text = mode.announcement || mode.label;
+    if (!text) return;
+
+    var toast = document.getElementById("fcm-toast");
+    if (!toast) {
+      toast = document.createElement("div");
+      toast.id = "fcm-toast";
+      toast.className = "fcm-toast";
+      toast.setAttribute("role", "status");
+      toast.setAttribute("aria-live", "polite");
+      document.body.appendChild(toast);
+    }
+    toast.textContent = text;
+
+    var header = document.querySelector(".md-header");
+    var headerBottom = header ? header.getBoundingClientRect().bottom : 0;
+    toast.style.top = Math.max(headerBottom, 0) + 12 + "px";
+
+    // Force a reflow so the transition restarts if the toast is already showing.
+    toast.classList.remove("fcm-toast--visible");
+    void toast.offsetWidth;
+    toast.classList.add("fcm-toast--visible");
+
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(function () {
+      toast.classList.remove("fcm-toast--visible");
+    }, 1400);
+  }
+
+  function buildToggle(config) {
+    var container = document.createElement("div");
+    container.id = "fcm-toggle";
+    container.className = "fcm-toggle";
+    container.setAttribute("role", "group");
+    container.setAttribute("aria-label", config.ariaLabel || "Content mode");
+    if (config.collapseLabels) container.setAttribute("data-collapse-labels", "");
+
+    var highlight = document.createElement("span");
+    highlight.className = "fcm-highlight";
+    highlight.setAttribute("aria-hidden", "true");
+    container.appendChild(highlight);
+
+    config.modes.forEach(function (mode) {
+      var option = document.createElement("button");
+      option.type = "button";
+      option.className = "fcm-option";
+      if (mode.icon) option.className += " fcm-option--icon";
+      option.dataset.name = mode.name;
+      if (mode.description) option.title = mode.description;
+      if (mode.icon) option.style.setProperty("--fcm-icon", mode.icon);
+
+      var label = document.createElement("span");
+      label.className = "fcm-label";
+      label.textContent = mode.label;
+      option.appendChild(label);
+
+      container.appendChild(option);
+    });
+
+    container.addEventListener("click", function (event) {
+      var option = event.target.closest(".fcm-option");
+      if (!option) return;
+      var name = option.dataset.name;
+      if (container.dataset.active === name) return;
+      localStorage.setItem(config.storageKey, name);
+      applyState(container, name, config);
+      var mode = config.modes.find(function (m) {
+        return m.name === name;
+      });
+      if (mode) showToast(mode, config);
+    });
+
+    return container;
+  }
+
+  function getOrCreateToggle(config) {
+    var existing = document.getElementById("fcm-toggle");
+    if (existing) return existing;
+
+    var anchor = config.insertSelector ? document.querySelector(config.insertSelector) : null;
+    var container = buildToggle(config);
+
+    if (anchor) {
+      anchor.insertAdjacentElement("beforebegin", container);
+    } else {
+      document.body.appendChild(container);
+    }
+
+    return container;
+  }
+
+  function marksMode(el, mode, config) {
+    var tokens = (el.getAttribute(config.attribute) || "").split(/\s+/).filter(Boolean);
+    return tokens.indexOf(mode) !== -1;
+  }
+
+  function headingLevel(el) {
+    return /^H[1-6]$/.test(el.tagName) ? Number(el.tagName[1]) : null;
+  }
+
+  // Same rules as setElementHidden, checked without changing the page.
+  function isHiddenInMode(el, mode, config) {
+    for (var node = el; node && node !== document.body; node = node.parentElement) {
+      if (marksMode(node, mode, config)) return true;
+
+      // An earlier sibling heading owns `node` if it's a higher level than
+      // `node` and every heading in between.
+      var limit = headingLevel(node) || 7;
+      for (var sib = node.previousElementSibling; sib && limit > 1; sib = sib.previousElementSibling) {
+        var level = headingLevel(sib);
+        if (level === null || level >= limit) continue;
+        if (marksMode(sib, mode, config)) return true;
+        limit = level;
+      }
+
+      var first = node.firstElementChild;
+      if (
+        first &&
+        headingLevel(first) &&
+        marksMode(first, mode, config) &&
+        (config.wrapperClasses || []).some(function (cls) {
+          return node.classList.contains(cls);
+        })
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  // Checks modes one position away from the current mode, then two, and so
+  // on. On a tie, the later mode in the list wins.
+  function findNearestVisibleMode(target, config, currentIndex) {
+    for (var distance = 1; distance < config.modes.length; distance++) {
+      var candidates = [currentIndex + distance, currentIndex - distance];
+      for (var i = 0; i < candidates.length; i++) {
+        var mode = config.modes[candidates[i]];
+        if (mode && !isHiddenInMode(target, mode.name, config)) return mode.name;
+      }
+    }
+    return null;
+  }
+
+  function revealHashTargetIfHidden(container, config) {
+    if (!location.hash) return;
+    var target = document.getElementById(decodeURIComponent(location.hash.slice(1)));
+    var current = container.dataset.active;
+    if (!target || !isHiddenInMode(target, current, config)) return;
+
+    var currentIndex = config.modes.findIndex(function (m) {
+      return m.name === current;
+    });
+    var nextMode = findNearestVisibleMode(target, config, currentIndex);
+    if (nextMode === null) return;
+
+    localStorage.setItem(config.storageKey, nextMode);
+    applyState(container, nextMode, config);
+  }
+
+  function setUp() {
+    var config = readConfig();
+    if (!config) return;
+
+    var container = getOrCreateToggle(config);
+
+    var initial = config.defaultMode;
+    var stored = localStorage.getItem(config.storageKey);
+    if (stored && config.modes.some(function (m) { return m.name === stored; })) {
+      initial = stored;
+    }
+    if (config.queryParam) {
+      var override = new URLSearchParams(window.location.search).get(config.queryParam);
+      if (override && config.modes.some(function (m) { return m.name === override; })) {
+        localStorage.setItem(config.storageKey, override);
+        initial = override;
+      }
+    }
+
+    applyState(container, initial, config);
+    revealHashTargetIfHidden(container, config);
+    refreshLayout();
+
+    // Label widths can change when a web font finishes loading.
+    if (document.fonts && document.fonts.ready) {
+      document.fonts.ready.then(refreshLayout);
+    }
+
+    // setUp runs on every page change with navigation.instant, so bind
+    // window listeners only once.
+    if (!window.__fcmHashRecoveryBound) {
+      window.__fcmHashRecoveryBound = true;
+      window.addEventListener("hashchange", function () {
+        var current = document.getElementById("fcm-toggle");
+        if (current) revealHashTargetIfHidden(current, config);
+      });
+    }
+
+    if (!window.__fcmResizeBound) {
+      window.__fcmResizeBound = true;
+      window.addEventListener("resize", refreshLayout);
+    }
+  }
+
+  // Material's document$ emits on every page change, including instant
+  // navigation, where DOMContentLoaded only fires once.
+  if (window.document$) {
+    window.document$.subscribe(setUp);
+  } else {
+    document.addEventListener("DOMContentLoaded", setUp);
+  }
+})();

mkdocs_audience_toggle-0.1.0.dist-info/METADATA

@@ -0,0 +1,380 @@
+Metadata-Version: 2.5
+Name: mkdocs-audience-toggle
+Version: 0.1.0
+Summary: Material for MkDocs plugin: an N-way content-mode toggle (e.g. Essentials/Advanced) that shows or hides marked content per mode.
+Project-URL: Homepage, https://github.com/luka-sherman/mkdocs-audience-toggle
+Author-email: Luka Sherman <luka.msherman@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Framework :: MkDocs
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: mkdocs>=1.5
+Provides-Extra: test
+Requires-Dist: mkdocs-material; extra == 'test'
+Requires-Dist: playwright; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-playwright; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mkdocs-audience-toggle
+
+A [MkDocs](https://www.mkdocs.org/) plugin (built for and tested with
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)) that adds a toggle to the header that allows the user to switch the content mode. A mode allows you to hide content sections that you do not want that audience to see. By default all content is otherwise available in all modes (see ["Marking content"](#marking-content)). State persists across pages via `localStorage`.
+
+With two modes, Beginner hides the advanced sections and Advanced shows everything. Switching
+modes updates the page without reloading it.
+
+```yaml
+plugins:
+  - audience_toggle:
+      modes:
+        - name: beginner
+          label: Beginner
+          icon: url(...)
+        - name: advanced
+          label: Advanced
+          default: true
+          icon: url(...)
+```
+
+![Two-mode toggle, "Beginner" and "Advanced", with icons](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/two-modes.png)
+
+In this example, the last two sections are marked `{: data-fcm-hide="beginner" }` (see
+["Marking content"](#marking-content)), so Beginner mode hides them:
+
+![The page in Beginner mode: two sections](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/content-two-modes-beginner.png)
+
+![The same page in Advanced mode: two more sections appear](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/content-two-modes-advanced.png)
+
+You can add more modes. Each mode's `icon` is optional.
+
+```yaml
+      modes:
+        - name: beginner
+          icon: url(...)
+        - name: intermediate
+          default: true
+          icon: url(...)
+        - name: advanced
+          icon: url(...)
+```
+
+![Three-mode toggle, "Beginner", "Intermediate", "Advanced"](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/three-modes.png)
+
+Each heading lists the modes it's hidden in, so sections can appear in stages:
+
+```markdown
+## Handling and health checks {: data-fcm-hide="beginner" }
+
+## Breeding cycles {: data-fcm-hide="beginner intermediate" }
+```
+
+![The page in Beginner mode: two sections](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/content-three-modes-beginner.png)
+
+![The same page in Intermediate mode: a third section appears](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/content-three-modes-intermediate.png)
+
+![The same page in Advanced mode: a fourth section appears](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/content-three-modes-advanced.png)
+
+Below a 45em viewport width, `collapse_labels` shows only the icons:
+
+```yaml
+      collapse_labels: true
+```
+
+![Two-mode toggle on a phone-width viewport, showing icons only](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/two-modes-mobile.png)
+
+Without `collapse_labels`, a toggle that doesn't fit in the header moves to its own row:
+
+![Three-mode toggle on a phone-width viewport, on its own row below the header](https://raw.githubusercontent.com/luka-sherman/mkdocs-audience-toggle/master/screenshots/three-modes-mobile.png)
+
+## Requirements
+
+Python 3.9+ and MkDocs 1.5+. The plugin doesn't depend on Material for MkDocs, but it was built
+and tested with it, and two options rely on Material's markup:
+
+- `insert_selector` defaults to Material's palette toggle. If nothing matches, the toggle is added
+  to the end of `<body>`. Set `insert_selector` to place it somewhere else.
+- `hide_toc_entries` hides entries in Material's table of contents. With other themes it does
+  nothing, but the content itself is still hidden.
+
+## Hidden content is not private
+
+Content is hidden in the browser with JavaScript and CSS. Every visitor downloads the full page in
+every mode, and hidden content can be read in the page source, with JavaScript turned off, or by
+switching modes. Don't use the plugin to restrict access to anything.
+
+MkDocs' `search` plugin indexes all content regardless of mode. A search result can point to a
+heading that's hidden in the current mode. Following it switches modes, as described in
+["Linking to hidden content"](#linking-to-hidden-content).
+
+## Install
+
+```bash
+pip install mkdocs-audience-toggle
+```
+
+## Configure
+
+```yaml
+plugins:
+  - audience_toggle:
+      modes:
+        - name: essentials
+          label: Essentials
+          default: true
+          description: Show only what you need to write your first programs
+          announcement: Just the basics, start here!
+          icon: url(...)
+        - name: advanced
+          label: Advanced
+          description: Show all site content
+          announcement: Viewing all content.
+          icon: url(...)
+```
+
+`modes` is required. List at least two. Each entry has these keys:
+
+| Key            | Required | Description                                                                  |
+| -------------- | -------- | ---------------------------------------------------------------------------- |
+| `name`         | yes      | Identifier used in `data-fcm-hide`, the URL parameter, and `localStorage`.  |
+| `label`        | no       | Button text. Defaults to `name.title()`.                                     |
+| `default`      | no       | Makes this the mode on a reader's first visit. Defaults to the first mode.  |
+| `icon`         | no       | A CSS `mask-image` value, such as `"url('data:image/svg+xml,...')"`.         |
+| `description`  | no       | Tooltip text for the mode's button.                                          |
+| `announcement` | no       | Text shown in the toast after switching to this mode. Defaults to `label`.   |
+
+Other options:
+
+| Key                | Default                         | Description                                                                 |
+| ------------------ | ------------------------------- | --------------------------------------------------------------------------- |
+| `storage_key`      | `fcm-mode`                      | `localStorage` key for the active mode.                                     |
+| `query_param`      | none                            | URL parameter that sets the mode, such as `?mode=advanced`.                 |
+| `insert_selector`  | `[data-md-component="palette"]` | The toggle is inserted before the first element matching this selector. If nothing matches, it's added to the end of `<body>`. |
+| `attribute`        | `data-fcm-hide`                 | Attribute used to mark content.                                             |
+| `hide_toc_entries` | `true`                          | Also hide a hidden heading's entry in Material's table of contents.         |
+| `wrapper_class`    | `[]`                            | Class names of wrapper elements to hide along with a marked heading, when the heading is the wrapper's first child. |
+| `aria_label`       | `Content mode`                  | Accessible label for the toggle.                                            |
+| `collapse_labels`  | `false`                         | Below a 45em viewport width, show only the icons. Every mode needs an `icon`. |
+| `show_toast`       | `true`                          | Show a short message after the mode changes.                                |
+
+Below 45em, if the toggle doesn't fit in Material's header row, it moves to its own row below it.
+When it fits, it stays next to the title.
+This needs browser support for CSS `:has()`. Without it, the toggle stays in the header row and
+can overflow on narrow screens.
+
+## Marking content
+
+The plugin hides elements whose `data-fcm-hide` attribute (or the attribute set in `attribute`)
+includes the active mode. The value is a space-separated list of mode names. There are three ways
+to add the attribute.
+
+### 1. `attr_list` attributes
+
+With the [`attr_list`](https://python-markdown.github.io/extensions/attr_list/) extension enabled
+in `markdown_extensions`, add the attribute to a heading, paragraph, list item, or admonition:
+
+```markdown
+## Decorators {: data-fcm-hide="essentials" }
+
+This section is hidden in Essentials mode.
+
+## Functions
+
+This paragraph is hidden in Essentials mode. The rest of the section is shown.
+{: data-fcm-hide="essentials" }
+```
+
+A marked heading hides its whole section, up to the next heading of the same or higher level. Any
+other marked element hides only itself.
+
+### 2. HTML wrappers
+
+To hide content that isn't a single block, wrap it in a `<div>` or `<span>` with the attribute. On
+a `<div>`, add `markdown="block"` (from the
+[`md_in_html`](https://python-markdown.github.io/extensions/md_in_html/) extension) so the Markdown
+inside it is still rendered:
+
+```markdown
+<div data-fcm-hide="essentials" markdown="block">
+This block is hidden in Essentials mode.
+</div>
+
+This sentence has <span data-fcm-hide="essentials">an inline aside</span> in it.
+```
+
+### 3. CSS for multi-paragraph list items
+
+The plugin hides only the marked element and, for a heading, its section. It doesn't hide parent
+elements. For a list item with more than one paragraph, such as a card in a Material
+[card grid](https://squidfunk.github.io/mkdocs-material/reference/grids/#using-card-grids),
+`attr_list` can only mark the first paragraph, not the `<li>`. To hide the whole item, add a CSS
+rule that uses the `data-fcm-mode` attribute the plugin sets on `<html>`:
+
+```css
+html[data-fcm-mode="essentials"] .grid.cards > ul > li:has(> p[data-fcm-hide~="essentials"]) {
+  display: none;
+}
+```
+
+The default mode is the one active on a reader's first visit. Content can be hidden in it like in
+any other mode.
+
+The attribute has no effect without the plugin. If you remove the plugin, all marked content is
+shown.
+
+## Linking to hidden content
+
+When a link points to content that's hidden in the reader's current mode, the plugin switches to
+the nearest mode that shows it. This works whether the target is marked itself or is hidden
+because of something around it, such as a subheading inside a hidden section or a heading inside
+a hidden `<div>`.
+
+Distance is measured from the current mode's position in the `modes` list: the plugin checks the
+modes one position away, then two, and so on. If two modes are the same distance away, it picks
+the one later in the list.
+
+For example, with the modes `beginner`, `intermediate`, and `advanced`, a heading marked
+`data-fcm-hide="beginner advanced"` is shown only in Intermediate. Following a link to it from
+Beginner or Advanced switches to Intermediate. A heading marked `data-fcm-hide="beginner"` is
+shown in both Intermediate and Advanced, so a Beginner reader following a link to it switches to
+Intermediate, the closer of the two.
+
+If the target is hidden in every mode, the mode doesn't change.
+
+### Setting the mode from a URL
+
+Set `query_param` to let a link choose the mode:
+
+```yaml
+      query_param: mode
+```
+
+```
+https://example.com/some-page/?mode=advanced
+```
+
+Opening this link switches to Advanced mode and saves it to `localStorage`, so the mode stays the
+same on other pages. Unrecognized values are ignored. To also jump to a section, add a heading
+anchor: `?mode=advanced#some-heading`.
+
+The parameter stays in the URL after the mode is applied. With Material's `navigation.instant`
+feature, Material rewrites the page's navigation links as absolute URLs, including the query
+string, before the plugin runs. If the plugin removed the parameter afterward, those links would no
+longer match the current URL, and clicking one would reload the page instead of scrolling to the
+heading.
+
+As a result, analytics tools that count page views by URL record the landing page as
+`/some-page/?mode=advanced`, separately from `/some-page/`. Only the page opened from the link is
+affected. To track modes without relying on the URL, use the event described in
+["Analytics"](#analytics).
+
+## Styling
+
+The toggle's CSS is controlled with custom properties. Override them in your `extra_css` file on
+`#fcm-toggle`, or on a parent element such as `:root`:
+
+```css
+#fcm-toggle {
+  --fcm-accent: #2e7d32;      /* border and highlight color (default: currentColor) */
+  --fcm-track-bg: #fdf6e3;    /* toggle background (default: transparent) */
+  --fcm-active-fg: #fdf6e3;   /* text color of the active option (default: Canvas) */
+  --fcm-radius: 1rem;         /* corner radius of the toggle and highlight (default: 1rem) */
+  --fcm-height: 1.2rem;       /* toggle height (default: 1.2rem) */
+  --fcm-font-size: 0.6rem;    /* label font size (default: 0.6rem) */
+  --fcm-icon-size: 0.7rem;    /* icon size (default: 0.7rem) */
+}
+```
+
+For other changes, target the classes `.fcm-toggle`, `.fcm-highlight`, `.fcm-option`,
+`.fcm-option--icon`, and `.fcm-label`. The script sets the highlight's `left` and `width` inline to
+match the active option.
+
+## Accessibility
+
+- The color properties aren't checked for contrast. Check your color choices against WCAG
+  contrast requirements.
+- With `collapse_labels: true`, give every mode an `icon`. Below 45em the labels are hidden
+  visually but still read by screen readers, so a mode without an icon appears as an empty button.
+- Each option is a toggle button with `aria-pressed` and its own tab stop. The toggle doesn't use
+  the ARIA radio group pattern, which has a single tab stop and arrow-key navigation.
+- The [card grid CSS rule](#3-css-for-multi-paragraph-list-items) and the toggle's mobile row both
+  need CSS `:has()` (Chrome 105+, Safari 15.4+, Firefox 121+). In older browsers, the card's first
+  paragraph is still hidden but the rest of the card isn't, and the toggle doesn't move to its own
+  row.
+- Transitions are turned off when `prefers-reduced-motion: reduce` is set.
+- Hidden content uses `display: none`, which removes it from the accessibility tree.
+- If the plugin's JavaScript doesn't run, no content is hidden.
+
+## Active mode attribute
+
+The plugin sets `data-fcm-mode` on `<html>` to the name of the active mode. Use it to style other
+elements or to read the mode from other scripts.
+
+## Analytics
+
+The plugin doesn't add the mode to URLs, so page views counted by URL don't include it. To record
+the mode, listen for the `fcm:modechange` event on `document`. `event.detail` contains `mode` and
+`previousMode`:
+
+```js
+document.addEventListener("fcm:modechange", (event) => {
+  const { mode, previousMode } = event.detail;
+  // Google Analytics (gtag.js)
+  gtag("event", "content_mode_change", { mode, previous_mode: previousMode });
+  // Plausible
+  plausible("Content Mode Change", { props: { mode } });
+});
+```
+
+The event fires when the plugin sets the mode on page load (`previousMode` is `null`) and each time
+the mode changes. Clicking the option that's already active doesn't fire it.
+
+A script that loads after the plugin, such as a tag manager snippet, misses the page-load event.
+Read `document.documentElement.dataset.fcmMode` when the script starts to get the current mode,
+then listen for the event.
+
+### Using a MutationObserver
+
+You can also watch the `data-fcm-mode` attribute instead of listening for the event. With
+`navigation.instant`, the plugin sets the attribute again on each page change even when the mode
+hasn't changed, so this example skips repeated values:
+
+```js
+const html = document.documentElement;
+let lastMode = null;
+
+function reportMode() {
+  const mode = html.dataset.fcmMode;
+  if (!mode || mode === lastMode) return;
+  gtag("event", "content_mode_change", { mode, previous_mode: lastMode });
+  lastMode = mode;
+}
+
+reportMode();
+new MutationObserver(reportMode).observe(html, { attributeFilter: ["data-fcm-mode"] });
+```
+
+## Testing
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[test]"
+playwright install chromium
+pytest
+```
+
+`tests/fixture_site/` is a small Material for MkDocs site that uses the plugin. The tests build it
+once, serve it locally, and run Playwright against it:
+
+- `test_behavior.py`: hiding, persistence, links to hidden content, and toggle layout.
+- `test_accessibility.py`: axe-core checks.
+- `test_keyboard.py`: keyboard use and focus.
+
+axe-core is included in `tests/vendor/`, so the tests don't need network access.
+
+## License
+
+[MIT](LICENSE)

mkdocs_audience_toggle-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mkdocs_audience_toggle/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocs_audience_toggle/plugin.py,sha256=H_OoWMcK_6YCC9j2c5wGtXlYM98v3p57mSlZgdvh3_g,4812
+mkdocs_audience_toggle/static/audience_toggle.css,sha256=9Hf7Hg6ary3SuQNlskDEBTFchBc9uUeuRqlWtgTmbfU,3363
+mkdocs_audience_toggle/static/audience_toggle.js,sha256=7PndlnMytWvlDqu2k4ou2kEOMrp4pQJx2VBNkyx-dR0,11561
+mkdocs_audience_toggle-0.1.0.dist-info/METADATA,sha256=qvzpoHBW6otBlLowe_EjuhSrM7qekrVxCXXXV51SC_c,17054
+mkdocs_audience_toggle-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mkdocs_audience_toggle-0.1.0.dist-info/entry_points.txt,sha256=OBXYINVvNwBBAKz4-JMkzTRZBe0lZGSvTO8N-ddOmjM,86
+mkdocs_audience_toggle-0.1.0.dist-info/licenses/LICENSE,sha256=8eSg7z3uZ_8PXMr30y4f3GlWv6ND5QUAIOB3eccrtc0,1069
+mkdocs_audience_toggle-0.1.0.dist-info/RECORD,,

mkdocs_audience_toggle-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mkdocs_audience_toggle-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+audience_toggle = mkdocs_audience_toggle.plugin:AudienceTogglePlugin

mkdocs_audience_toggle-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.