MkDocs UI/UX & Kubernetes-Style Sidebar Navigation: Complete Reference & Migration Blueprint¶

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                NECTAR MODERN PORTAL                                    │
├────────────────────────────────────────────────────────────────────────────────────────┤
│  Top Navigation Bar: 10 First-Class Tabs (Stable, Zero-Wrap, Sticky Blur Header)       │
├───────────────────────────────┬────────────────────────────────────────────────────────┤
│  LEFT SIDEBAR NAVIGATION      │  MAIN CONTENT & HOMEPAGE HERO                          │
│  (Kubernetes.io Paradigm)     │                                                        │
│                               │  [2-Column Desktop Grid @ >= 1080px]                   │
│  ▶ Home                       │  Left: High-Impact Editorial & CTAs                    │
│  ▼ Containers & Orchestration │  - Live Pill Badge ("✦ Living Knowledge Base")         │
│    ▶ Architecture & Core      │  - H1 Display Heading with Gradient Accent             │
│    ▼ Kubernetes Workloads     │  - Dual Action Buttons (Solid Accent + Ghost Glass)    │
│      • Deployments & Rollouts │  - Credibility Stats Row (Certifications, Domains)     │
│      • StatefulSets & Storage │                                                        │
│    ▶ Networking & Ingress     │  Right: macOS Developer Terminal Window (.nx-terminal) │
│  ▶ Cloud & Infrastructure     │  - Traffic Light Controls (Red, Yellow, Green)         │
│  ▶ CI/CD & Delivery           │  - Active Tab Pill ("nectar-diagnostics.sh")           │
│                               │  - Monospace Syntax Diagnostic Output & Status Checks  │
└───────────────────────────────┴────────────────────────────────────────────────────────┘

flex: 0 0 1.15rem !important;
width: 1.15rem !important;
min-width: 1.15rem !important;
max-width: 1.15rem !important;
margin: 0 !important;
padding: 0 !important;

{% if nav_item.children | length > 1 and not is_section %}
  <label class="md-nav__link md-nav__link--toggle ...">
    <span class="md-nav__icon md-icon"></span>
  </label>
{% endif %}

.md-nav--primary .md-nav__list .md-nav__list {
  padding-left: 0.85rem !important;
  margin-left: 0 !important;
  border-left: none !important;
}

repo-root/
├── mkdocs.yml                            # 1. Feature flags, tabs, typography & theme
└── docs/
    ├── overrides/
    │   └── partials/
    │       └── nav-item.html             # 2. Jinja2 template override (left carets & section guards)
    └── stylesheets/
        └── extra.css                     # 3. Design system tokens, caret alignment & Obsidian theme

theme:
  name: material
  language: en
  custom_dir: docs/overrides
  font:
    text: Inter
    code: JetBrains Mono
  features:
    - navigation.instant
    - navigation.instant.progress
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.path
    - navigation.indexes
    - navigation.top
    - toc.follow
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.tabs.link
    - content.tooltips
    # CRITICAL: DO NOT enable navigation.sections (breaks collapsible tree)
    # CRITICAL: DO NOT enable navigation.prune (breaks instant client-side expansion)
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

extra_css:
  - docs/stylesheets/extra.css

{#-
  Custom Navigation Item Template for MkDocs Material
  Enables Kubernetes.io-style left carets and eliminates non-functional section header toggles.
-#}
{% macro render_status(nav_item, type) %}
  {% set class = "md-status md-status--" ~ type %}
  {% if config.extra.status and config.extra.status[type] %}
    <span class="{{ class }}" title="{{ config.extra.status[type] }}">
    </span>
  {% else %}
    <span class="{{ class }}"></span>
  {% endif %}
{% endmacro %}
{% macro render_title(nav_item) %}
  {% if nav_item.typeset %}
    <span class="md-typeset">
      {{ nav_item.typeset.title }}
    </span>
  {% else %}
    {{ nav_item.title }}
  {% endif %}
{% endmacro %}
{% macro render_content(nav_item, ref) %}
  {% set ref = ref or nav_item %}
  {% if nav_item.meta and nav_item.meta.icon %}
    {% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %}
  {% endif %}
  <span class="md-ellipsis">
    {{ render_title(ref) }}
    {% if nav_item.meta and nav_item.meta.subtitle %}
      <br>
      <small>{{ nav_item.meta.subtitle }}</small>
    {% endif %}
  </span>
  {% if nav_item.meta and nav_item.encrypted %}
    {{ render_status(nav_item, "encrypted") }}
  {% endif %}
  {% if nav_item.meta and nav_item.meta.status %}
    {{ render_status(nav_item, nav_item.meta.status) }}
  {% endif %}
{% endmacro %}
{% macro render_pruned(nav_item, ref) %}
  {% set ref = ref or nav_item %}
  {% set first = nav_item.children | first %}
  {% if first and first.children %}
    {{ render_pruned(first, ref) }}
  {% else %}
    <a href="{{ first.url | url }}" class="md-nav__link">
      {% if nav_item.children | length > 0 %}
        <span class="md-nav__icon md-icon"></span>
      {% endif %}
      {{ render_content(ref) }}
    </a>
  {% endif %}
{% endmacro %}
{% macro render(nav_item, path, level, parent) %}
  {% set class = "md-nav__item" %}
  {% if nav_item.active %}
    {% set class = class ~ " md-nav__item--active" %}
  {% endif %}
  {% if nav_item.pages %}
    {% if page in nav_item.pages %}
      {% set nav_item = page %}
    {% endif %}
  {% endif %}
  {% if nav_item.children %}
    {% set _ = namespace(index = none) %}
    {% if "navigation.indexes" in features %}
      {% for item in nav_item.children %}
        {% if item.is_index and _.index is none %}
          {% set _.index = item %}
        {% endif %}
      {% endfor %}
    {% endif %}
    {% set index = _.index %}
    {% if "navigation.tabs" in features %}
      {% if level == 1 and nav_item.active %}
        {% set class = class ~ " md-nav__item--section" %}
        {% set is_section = true %}
      {% endif %}
      {% if "navigation.sections" in features %}
        {% if level == 2 and parent.active %}
          {% set class = class ~ " md-nav__item--section" %}
          {% set is_section = true %}
        {% endif %}
      {% endif %}
    {% elif "navigation.sections" in features %}
      {% if level == 1 %}
        {% set class = class ~ " md-nav__item--section" %}
        {% set is_section = true %}
      {% endif %}
    {% endif %}
    {% if "navigation.prune" in features %}
      {% if not is_section and not nav_item.active %}
        {% set class = class ~ " md-nav__item--pruned" %}
        {% set is_pruned = true %}
      {% endif %}
    {% endif %}
    <li class="{{ class }} md-nav__item--nested">
      {% if not is_pruned %}
        {% set checked = "checked" if nav_item.active %}
        {% if "navigation.expand" in features and not checked %}
          {% set indeterminate = "md-toggle--indeterminate" %}
        {% endif %}
        <input class="md-nav__toggle md-toggle {{ indeterminate }}" type="checkbox" id="{{ path }}" {{ checked }}>
        {% if not index %}
          {% set tabindex = "0" if not is_section else "-1" %}
          <label class="md-nav__link" for="{{ path }}" id="{{ path }}_label" tabindex="{{ tabindex }}">
            {% if not is_section %}
              <span class="md-nav__icon md-icon"></span>
            {% endif %}
            {{ render_content(nav_item) }}
          </label>
        {% else %}
          {% set class = "md-nav__link--active" if index == page %}
          <div class="md-nav__link md-nav__container">
            {% if nav_item.children | length > 1 and not is_section %}
              {% set tabindex = "0" %}
              <label class="md-nav__link md-nav__link--toggle {{ class }}" for="{{ path }}" id="{{ path }}_label" tabindex="{{ tabindex }}">
                <span class="md-nav__icon md-icon"></span>
              </label>
            {% endif %}
            <a href="{{ index.url | url }}" class="md-nav__link {{ class }}">
              {{ render_content(index, nav_item) }}
            </a>
          </div>
        {% endif %}
        <nav class="md-nav" data-md-level="{{ level }}" aria-labelledby="{{ path }}_label" aria-expanded="{{ nav_item.active | tojson }}">
          <label class="md-nav__title" for="{{ path }}">
            <span class="md-nav__icon md-icon"></span>
            {{ render_title(nav_item) }}
          </label>
          <ul class="md-nav__list" data-md-scrollfix>
            {% for item in nav_item.children %}
              {% if not index or item != index %}
                {{ render(item, path ~ "_" ~ loop.index, level + 1, nav_item) }}
              {% endif %}
            {% endfor %}
          </ul>
        </nav>
      {% else %}
        {{ render_pruned(nav_item) }}
      {% endif %}
    </li>
  {% elif nav_item == page %}
    <li class="{{ class }}">
      <a href="{{ nav_item.url | url }}" class="md-nav__link md-nav__link--active">
        {{ render_content(nav_item) }}
      </a>
    </li>
  {% else %}
    <li class="{{ class }}">
      <a href="{{ nav_item.url | url }}" class="md-nav__link">
        {{ render_content(nav_item) }}
      </a>
    </li>
  {% endif %}
{% endmacro %}

/* ==========================================================================
   1. TYPOGRAPHY & DESIGN SYSTEM COLOR TOKENS
   ========================================================================== */

@import url('https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,300..700;1,14..32,300..700&family=JetBrains+Mono:ital,wght@0,400..600;1,400..600&display=swap');

:root {
  --nx-font-sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  --nx-font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
  --nx-radius-sm: 6px;
  --nx-radius-md: 8px;
  --nx-radius-lg: 12px;
  --nx-radius-xl: 16px;
  --nx-radius-pill: 9999px;
  --nx-content-max: 76rem; /* Option A: ~1520px at 20px rem scale */
}

/* Light Mode: Frosted Clean White */
[data-md-color-scheme="default"] {
  --md-primary-fg-color:          #2563eb;
  --md-primary-fg-color--light:   #3b82f6;
  --md-primary-fg-color--dark:    #1d4ed8;
  --md-primary-bg-color:          #ffffff;
  --md-primary-bg-color--light:   #f8fafc;
  --md-accent-fg-color:           #2563eb;
  --md-typeset-a-color:           #2563eb;

  --md-default-bg-color:          #fafafa;
  --md-default-bg-color--light:   #ffffff;
  --md-default-bg-color--lighter: #f4f4f5;
  --md-default-fg-color:          #09090b;
  --md-default-fg-color--light:   #52525b;
  --md-default-fg-color--lighter: #71717a;
  --md-default-fg-color--lightest:#e4e4e7;

  --nx-header-bg:                 rgba(255, 255, 255, 0.88);
  --nx-header-border:             #e4e4e7;
  --nx-header-fg:                 #09090b;
  --nx-card-bg:                   #ffffff;
  --nx-card-border:               #e4e4e7;
  --nx-card-border-hover:         #cbd5e1;
  --nx-accent-soft:               rgba(37, 99, 235, 0.06);
  --nx-accent-soft-2:             rgba(37, 99, 235, 0.12);
  --nx-accent-ring:               rgba(37, 99, 235, 0.20);
}

/* Dark Mode: True Obsidian Black */
[data-md-color-scheme="slate"] {
  --md-primary-fg-color:          #3b82f6;
  --md-primary-fg-color--light:   #60a5fa;
  --md-primary-fg-color--dark:    #2563eb;
  --md-primary-bg-color:          #09090b;
  --md-primary-bg-color--light:   #121215;
  --md-accent-fg-color:           #60a5fa;
  --md-typeset-a-color:           #60a5fa;

  --md-default-bg-color:          #09090b;
  --md-default-bg-color--light:   #121215;
  --md-default-bg-color--lighter: #18181b;
  --md-default-fg-color:          #f4f4f5;
  --md-default-fg-color--light:   #a1a1aa;
  --md-default-fg-color--lighter: #71717a;
  --md-default-fg-color--lightest:#27272a;

  --nx-header-bg:                 rgba(9, 9, 11, 0.85);
  --nx-header-border:             rgba(255, 255, 255, 0.08);
  --nx-header-fg:                 #f4f4f5;
  --nx-card-bg:                   #111114;
  --nx-card-border:               rgba(255, 255, 255, 0.08);
  --nx-card-border-hover:         rgba(255, 255, 255, 0.18);
  --nx-accent-soft:               rgba(59, 130, 246, 0.08);
  --nx-accent-soft-2:             rgba(59, 130, 246, 0.15);
  --nx-accent-ring:               rgba(59, 130, 246, 0.22);
}

html, body {
  font-family: var(--nx-font-sans);
  -webkit-font-smoothing: antialiased;
}

/* ==========================================================================
   2. KUBERNETES.IO-STYLE LEFT SIDEBAR TREE NAVIGATION
   ========================================================================== */

/* Base Link Styling */
.md-nav--primary .md-nav__link {
  display: flex !important;
  align-items: center !important;
  font-family: var(--nx-font-sans);
  font-size: 0.82rem;
  font-weight: 450;
  border-radius: 4px;
  padding: 0.35rem 0.6rem !important;
  color: var(--md-default-fg-color--light);
  transition: background-color 0.15s ease, color 0.15s ease;
}

/* Hover States */
[data-md-color-scheme="slate"] .md-nav--primary .md-nav__link:hover:not(.md-nav__container > .md-nav__link),
[data-md-color-scheme="slate"] .md-nav--primary .md-nav__container:hover {
  background-color: rgba(255, 255, 255, 0.04) !important;
  color: var(--md-default-fg-color) !important;
  border-radius: 4px !important;
}

[data-md-color-scheme="default"] .md-nav--primary .md-nav__link:hover:not(.md-nav__container > .md-nav__link),
[data-md-color-scheme="default"] .md-nav--primary .md-nav__container:hover {
  background-color: rgba(0, 0, 0, 0.03) !important;
  color: var(--md-default-fg-color) !important;
  border-radius: 4px !important;
}

/* Primary Active Item */
[data-md-color-scheme="slate"] .md-nav--primary .md-nav__link--active {
  color: #38bdf8 !important;
  font-weight: 600 !important;
}
[data-md-color-scheme="default"] .md-nav--primary .md-nav__link--active {
  color: #2563eb !important;
  font-weight: 600 !important;
}

/* Container for sections with index page (navigation.indexes) */
.md-nav--primary .md-nav__container {
  display: flex !important;
  align-items: center !important;
  padding: 0.35rem 0.6rem !important;
  margin: 0 !important;
  border-radius: 4px;
  transition: background-color 0.15s ease;
}

/* Caret Toggle Button inside Container: Locked Dimensions */
.md-nav--primary .md-nav__container > label.md-nav__link,
.md-nav--primary .md-nav__container > label.md-nav__link--toggle {
  order: -1 !important;
  flex: 0 0 1.15rem !important;
  width: 1.15rem !important;
  min-width: 1.15rem !important;
  max-width: 1.15rem !important;
  height: 1.15rem !important;
  margin: 0 !important;
  padding: 0 !important;
  background: transparent !important;
  cursor: pointer;
  display: inline-flex !important;
  align-items: center !important;
  justify-content: center !important;
}

/* Link Title inside Container: Spans Remaining Space with 0.45rem Gap */
.md-nav--primary .md-nav__container > a.md-nav__link {
  flex: 1 1 auto !important;
  min-width: 0 !important;
  padding: 0 !important;
  margin: 0 0 0 0.45rem !important;
  background: transparent !important;
  display: inline-flex !important;
  align-items: center !important;
}

/* Defensively hide in-page TOC toggle and nested TOC list in left primary navigation */
.md-nav--primary label[for="__toc"],
.md-nav--primary input[id="__toc"],
.md-nav--primary [for="__toc"] ~ .md-nav {
  display: none !important;
}

/* Direct Label for Sections Without an Index Page */
.md-nav--primary .md-nav__item--nested > label.md-nav__link,
.md-nav--primary .md-nav__item > label.md-nav__link:not([for="__toc"]) {
  padding: 0.35rem 0.6rem !important;
  display: flex !important;
  align-items: center !important;
  margin: 0 !important;
}

.md-nav--primary .md-nav__item--nested > label.md-nav__link .md-nav__icon,
.md-nav--primary .md-nav__item > label.md-nav__link:not([for="__toc"]) .md-nav__icon {
  margin: 0 0.45rem 0 0 !important;
}

/* Caret Icon Box: Anchored on LEFT */
.md-nav--primary .md-nav__link .md-nav__icon {
  order: -1 !important;
  margin-right: 0.45rem !important;
  margin-left: 0 !important;
  width: 1.15rem !important;
  height: 1.15rem !important;
  display: inline-flex !important;
  align-items: center !important;
  justify-content: center !important;
  flex-shrink: 0;
  border-radius: 4px;
  cursor: pointer;
  color: var(--md-default-fg-color--lighter);
  transition: color 0.15s ease, background-color 0.15s ease;
}

.md-nav--primary .md-nav__container > label.md-nav__link .md-nav__icon,
.md-nav--primary .md-nav__container > label.md-nav__link--toggle .md-nav__icon {
  margin: 0 !important;
  width: 1.15rem !important;
  height: 1.15rem !important;
}

/* Crisp Filled Triangle Caret (Collapsed: points right ▶) */
.md-nav--primary .md-nav__link .md-nav__icon:after {
  content: "" !important;
  display: block !important;
  width: 0.55rem !important;
  height: 0.55rem !important;
  background-color: currentColor !important;
  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M8 5v14l11-7z' fill='%23000'/%3E%3C/svg%3E") !important;
  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M8 5v14l11-7z' fill='%23000'/%3E%3C/svg%3E") !important;
  -webkit-mask-repeat: no-repeat !important;
  mask-repeat: no-repeat !important;
  -webkit-mask-position: center !important;
  mask-position: center !important;
  -webkit-mask-size: contain !important;
  mask-size: contain !important;
  transform: rotate(0deg);
  transition: transform 0.15s cubic-bezier(0.4, 0, 0.2, 1) !important;
  transform-origin: center center !important;
}

/* Expanded State: Rotates 90deg to point down ▼ */
.md-nav__item--nested > .md-nav__toggle:checked ~ .md-nav__link .md-nav__icon:after,
.md-nav__item--nested > .md-toggle--indeterminate ~ .md-nav__link .md-nav__icon:after,
.md-nav__item--nested > .md-nav__toggle:checked ~ .md-nav__container .md-nav__icon:after,
.md-nav__item--nested > .md-toggle--indeterminate ~ .md-nav__container .md-nav__icon:after {
  transform: rotate(90deg) !important;
}

/* Indentation Hierarchy (Kubernetes.io Standard - No Vertical Lines) */
.md-nav--primary .md-nav__list .md-nav__list {
  padding-left: 0.85rem !important;
  margin-left: 0 !important;
  border-left: none !important;
}

/* Top-Level Section Header Styling */
.md-nav--primary .md-nav__item--section > .md-nav__link,
.md-nav--primary .md-nav__item--section > .md-nav__container > a.md-nav__link {
  font-family: var(--nx-font-sans);
  font-weight: 700;
  letter-spacing: -0.01em;
  color: var(--md-default-fg-color) !important;
  font-size: 0.88rem;
  padding: 0.5rem 0.6rem 0.35rem !important;
  margin: 0 !important;
}

/* ==========================================================================
   3. MACOS DEVELOPER TERMINAL (.nx-terminal) & HERO SHOWCASE
   ========================================================================== */

.nx-hero {
  position: relative;
  overflow: hidden;
  padding: 2.5rem 2rem;
  margin: 0.75rem 0 2.5rem;
  border-radius: var(--nx-radius-xl);
  border: 1px solid var(--nx-card-border);
  background: var(--nx-card-bg);
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.05);
}

.nx-hero__inner {
  display: grid;
  grid-template-columns: 1fr;
  gap: 2.25rem;
  align-items: center;
}

@media screen and (min-width: 1080px) {
  .nx-hero__inner {
    grid-template-columns: 1.08fr 0.92fr;
  }
}

.nx-terminal {
  border-radius: var(--nx-radius-lg);
  overflow: hidden;
  font-family: var(--nx-font-mono);
  box-shadow: 0 12px 36px rgba(0, 0, 0, 0.45);
  border: 1px solid rgba(255, 255, 255, 0.08);
  background: #09090b;
}

.nx-terminal__header {
  display: flex;
  align-items: center;
  padding: 0.65rem 0.95rem;
  background: #111114;
  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
}

.nx-terminal__controls {
  display: flex;
  align-items: center;
  gap: 0.4rem;
  margin-right: 0.85rem;
}

.nx-terminal__dot {
  width: 11px;
  height: 11px;
  border-radius: 50%;
  display: inline-block;
}
.nx-terminal__dot--red    { background-color: #ff5f56; }
.nx-terminal__dot--yellow { background-color: #ffbd2e; }
.nx-terminal__dot--green  { background-color: #27c93f; }

.nx-terminal__tab {
  display: inline-flex;
  align-items: center;
  gap: 0.45rem;
  padding: 0.2rem 0.65rem;
  border-radius: 4px;
  background: #18181b;
  font-size: 0.73rem;
  color: #a1a1aa;
}

.nx-terminal__body {
  padding: 1.1rem 1.25rem;
  font-size: 0.8rem;
  line-height: 1.65;
  color: #f4f4f5;
}

.nx-terminal__row--cmd {
  display: flex;
  align-items: center;
  gap: 0.55rem;
  margin-bottom: 0.75rem;
}

.nx-terminal__prompt { color: #3b82f6; font-weight: 700; }
.nx-terminal__cmd    { color: #f4f4f5; font-weight: 600; }
.nx-terminal__check  { color: #10b981; font-weight: 700; margin-right: 0.4rem; }
.nx-terminal__label  { color: #71717a; margin-right: 0.35rem; }
.nx-terminal__val    { color: #e4e4e7; }

┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                OPTION A: 3 ADAPTIVE VIEW MODES                                  │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 1. DESKTOP VIEW (>= 1280px / 80em): Full 3-Column Canvas                                        │
│ ┌───────────────────────┬─────────────────────────────────────────────┬───────────────────────┐ │
│ │ PRIMARY SIDEBAR       │ MAIN CONTENT AREA (51.8rem / ~1036px)       │ SECONDARY TOC         │ │
│ │ Tree Navigation       │ Prose, Code Manifests, Tables, Hero         │ In-Page Headings      │ │
│ │ (12.1rem / 242px)     │ (Max Container: 76rem / ~1520px)            │ (12.1rem / 242px)     │ │
│ └───────────────────────┴─────────────────────────────────────────────┴───────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 2. LAPTOP VIEW (960px - 1279px / 60em - 79.9375em): Auto-Collapsed Secondary TOC               │
│ ┌───────────────────────┬─────────────────────────────────────────────────────────────────────┐ │
│ │ PRIMARY SIDEBAR       │ EXPANDED CONTENT TRACK (100% Remaining Width)                       │ │
│ │ Tree Navigation       │ Full horizontal space allocated to technical prose and code blocks  │ │
│ │ (12.1rem / 242px)     │ Secondary TOC hidden automatically; zero horizontal scroll clipping  │ │
│ └───────────────────────┴─────────────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 3. DISTRACTION-FREE FOCUS MODE (body.nx-focus-mode): Full Immersion (`Z` toggle, `Esc` exit)    │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │                       PROSE TRACK CENTERED (54rem / ~1080px)                                │ │
│ │         Technical prose restricted to optimal reading width for high legibility             │ │
│ │ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │ │
│ │ │                 TECHNICAL ASSETS EXPANDED (72rem / ~1440px)                             │ │ │
│ │ │                 Code Blocks, Tables, Terminal Windows, Admonitions                      │ │ │
│ │ └─────────────────────────────────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────────────────────┘

:root {
  --nx-content-max: 76rem; /* Option A: ~1520px at 20px rem scale */
}

.md-grid {
  max-width: var(--nx-content-max);
  margin-left: auto;
  margin-right: auto;
  padding-left: 1.25rem !important;
  padding-right: 1.25rem !important;
}

/* ==========================================================================
   OPTION A: LAPTOP RESPONSIVE AUTO-COLLAPSE (960px - 1279px)
   Hides secondary TOC on mid-range viewports to maximize code/manifest space.
   ========================================================================== */

@media screen and (min-width: 60em) and (max-width: 79.9375em) {
  /* Suppress secondary table of contents sidebar */
  .md-sidebar--secondary {
    display: none !important;
  }

  /* Expand content area to consume entire remaining horizontal track */
  .md-content {
    max-width: 100% !important;
  }

  .md-content__inner {
    margin-right: 0 !important;
  }
}

/* ==========================================================================
   OPTION A: FOCUS MODE INTERACTION & PERSISTENCE ENGINE
   Handles toggle button, Z / Escape keybindings, and sessionStorage sync.
   ========================================================================== */

(function () {
  var FOCUS_KEY = "nx-focus-mode";
  var FOCUS_CLASS = "nx-focus-mode";

  function setFocusMode(enabled) {
    if (enabled) {
      document.body.classList.add(FOCUS_CLASS);
      try { sessionStorage.setItem(FOCUS_KEY, "enabled"); } catch (e) {}
    } else {
      document.body.classList.remove(FOCUS_CLASS);
      try { sessionStorage.setItem(FOCUS_KEY, "disabled"); } catch (e) {}
    }
    updateFocusButtons(enabled);
  }

  function toggleFocusMode() {
    var isCurrentlyFocused = document.body.classList.contains(FOCUS_CLASS);
    setFocusMode(!isCurrentlyFocused);
  }

  function updateFocusButtons(enabled) {
    var buttons = document.querySelectorAll(".nx-focus-btn");
    buttons.forEach(function (btn) {
      btn.setAttribute("aria-pressed", enabled ? "true" : "false");
      btn.classList.toggle("nx-focus-btn--active", enabled);
    });
  }

  function initFocusMode() {
    // Restore persistent session state
    var savedState = null;
    try { savedState = sessionStorage.getItem(FOCUS_KEY); } catch (e) {}
    if (savedState === "enabled") {
      document.body.classList.add(FOCUS_CLASS);
      updateFocusButtons(true);
    } else {
      updateFocusButtons(false);
    }

    // Attach click listeners to all focus toggle buttons in DOM
    var buttons = document.querySelectorAll(".nx-focus-btn");
    buttons.forEach(function (btn) {
      if (!btn.dataset.focusBound) {
        btn.dataset.focusBound = "true";
        btn.addEventListener("click", function (e) {
          e.preventDefault();
          toggleFocusMode();
        });
      }
    });
  }

  // Global Keyboard Navigation Controller
  window.addEventListener("keydown", function (e) {
    // Ignore keystrokes when active element is an input, textarea, or content-editable
    var target = e.target;
    var tagName = target.tagName;
    if (
      tagName === "INPUT" ||
      tagName === "TEXTAREA" ||
      tagName === "SELECT" ||
      target.isContentEditable ||
      target.closest(".md-search__input")
    ) {
      return;
    }

    // Key 'Z' toggles focus mode
    if ((e.key === "z" || e.key === "Z") && !e.ctrlKey && !e.altKey && !e.metaKey) {
      e.preventDefault();
      toggleFocusMode();
    }

    // Key 'Escape' exits focus mode
    if (e.key === "Escape" && document.body.classList.contains(FOCUS_CLASS)) {
      e.preventDefault();
      setFocusMode(false);
    }
  });

  // Lifecycle registration: standard DOM ready + MkDocs instant navigation
  if (typeof document$ !== "undefined" && document$.subscribe) {
    document$.subscribe(initFocusMode);
  } else {
    document.addEventListener("DOMContentLoaded", initFocusMode);
  }
})();

/* ==========================================================================
   OPTION A: FOCUS MODE LAYOUT RULES (body.nx-focus-mode)
   ========================================================================== */

/* 1. Focus Mode Header Button */
.nx-focus-btn {
  width: 2rem;
  height: 2rem;
  border-radius: var(--nx-radius-sm);
  display: inline-flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;
  border: none;
  background: transparent;
  color: var(--nx-header-fg-dim);
  transition: all 0.2s ease;
  margin-right: 0.5rem;
  padding: 0;
  flex-shrink: 0;
}

.nx-focus-btn:hover {
  color: var(--nx-header-fg);
  background: rgba(0, 0, 0, 0.05);
}

[data-md-color-scheme="slate"] .nx-focus-btn:hover {
  background: rgba(255, 255, 255, 0.08);
}

body.nx-focus-mode .nx-focus-btn {
  color: var(--md-primary-fg-color);
  background: var(--nx-accent-soft-2);
}

.nx-focus-btn svg {
  width: 1.15rem;
  height: 1.15rem;
  fill: currentColor;
}

/* 2. Hide Primary & Secondary Sidebars */
body.nx-focus-mode .md-sidebar--primary,
body.nx-focus-mode .md-sidebar--secondary {
  display: none !important;
}

/* 3. Expand Content Track to 100% Container */
body.nx-focus-mode .md-main__inner {
  display: flex !important;
  justify-content: center !important;
  max-width: 100% !important;
  margin-left: auto !important;
  margin-right: auto !important;
}

body.nx-focus-mode .md-content {
  max-width: 100% !important;
  width: 100% !important;
  margin-left: auto !important;
  margin-right: auto !important;
}

/* 4. Single Centered Reading Canvas (76rem): All elements share the exact same left rail */
body.nx-focus-mode .md-content__inner {
  max-width: 76rem !important;
  width: 100% !important;
  margin-left: auto !important;
  margin-right: auto !important;
  padding-left: 1.5rem !important;
  padding-right: 1.5rem !important;
}

/* 5. Unified Left Rail Alignment: Headings, text, code, tables, and terminals share identical start position */
.nx-focus-mode .md-typeset > p,
.nx-focus-mode .md-typeset > ul,
.nx-focus-mode .md-typeset > ol,
.nx-focus-mode .md-typeset > blockquote,
.nx-focus-mode .md-typeset > h1,
.nx-focus-mode .md-typeset > h2,
.nx-focus-mode .md-typeset > h3,
.nx-focus-mode .md-typeset > h4,
.nx-focus-mode .highlight,
.nx-focus-mode .md-typeset__scrollwrap,
.nx-focus-mode .md-typeset__table,
.nx-focus-mode .mermaid,
.nx-focus-mode .admonition,
.nx-focus-mode .tabbed-set {
  margin-left: 0 !important;
  margin-right: 0 !important;
  width: 100% !important;
  max-width: 100% !important;
}

MIGRATION FLOW:
┌────────────────────┐     ┌────────────────────────────┐     ┌────────────────────────┐     ┌────────────────────────┐     ┌─────────────────────┐
│  STEP 1: CONFIG    │ ──> │  STEP 2: JINJA OVERRIDE    │ ──> │  STEP 3: CSS INJECTION │ ──> │  STEP 4: JS INJECTION  │ ──> │  STEP 5: VERIFY     │
│  Update mkdocs.yml │     │  Create nav-item.html      │     │  Append to extra.css   │     │  Append to extra.js    │     │  Build & Inspect    │
└────────────────────┘     └────────────────────────────┘     └────────────────────────┘     └────────────────────────┘     └─────────────────────┘

theme:
  name: material
  custom_dir: docs/overrides
  font:
    text: Inter
    code: JetBrains Mono
  features:
    - navigation.tabs
    - navigation.indexes
    # REMOVE: - navigation.sections
    # REMOVE: - navigation.prune

extra_css:
  - docs/stylesheets/extra.css

extra_javascript:
  - docs/javascripts/extra.js

# Build the site
mkdocs build --strict

# Or serve locally for live visual QA
mkdocs serve

I have an MkDocs repository using the Material for MkDocs theme. I want to upgrade the site to match the Kubernetes.io-style collapsible tree navigation, modern Obsidian Dark / Frosted Light UI standards, and the Option A adaptive layout architecture.

Please inspect this repository and apply the following architectural changes:

1. In `mkdocs.yml`:
   - Set `theme.custom_dir: docs/overrides`.
   - Set `theme.font.text: Inter` and `theme.font.code: JetBrains Mono`.
   - In `theme.features`, ensure `navigation.tabs` and `navigation.indexes` are present.
   - Crucially, ensure `navigation.sections` and `navigation.prune` are REMOVED (they break collapsible trees and client-side branch expansion).
   - Ensure `docs/stylesheets/extra.css` is included under `extra_css`.
   - Ensure `docs/javascripts/extra.js` is included under `extra_javascript`.

2. In `docs/overrides/partials/nav-item.html`:
   - Create this file (and parent directories if missing).
   - Implement the Jinja2 navigation item macro override that:
     a) Places the toggle caret on the LEFT of directory titles.
     b) Guards section headers with `and not is_section` so static domain titles never display non-functional toggle arrows.
     c) Wraps index-bearing items in `.md-nav__container` with a dedicated toggle `<label>`.

3. In `docs/stylesheets/extra.css`:
   - Add the design tokens for True Obsidian Black (`#09090b` canvas in dark mode) and Frosted Light (`#fafafa` canvas in light mode).
   - Configure Option A container max-width: `--nx-content-max: 76rem;`.
   - Add the Kubernetes.io sidebar CSS rules:
     a) Lock the toggle label width inside `.md-nav__container` to `flex: 0 0 1.15rem !important; width: 1.15rem !important; margin: 0 !important; padding: 0 !important;`.
     b) Scope direct item labels to `.md-nav--primary .md-nav__item > label.md-nav__link`.
     c) Set the link text to `flex: 1 1 auto !important; margin: 0 0 0 0.45rem !important;`.
     d) Implement crisp SVG filled triangle carets (rightward ▶ rotating 90deg to downward ▼) via `-webkit-mask-image` / `mask-image`.
     e) Remove vertical list borders (`border-left: none !important;`) and apply clean whitespace indentation (`padding-left: 0.85rem !important;`).
   - Add Option A responsive auto-collapse rules:
     Between `60em` (960px) and `79.9375em` (1279px), hide `.md-sidebar--secondary` and expand `.md-content` to 100%.
   - Add Option A Focus Mode rules:
     When `body.nx-focus-mode` is active, hide primary and secondary sidebars, center prose at `54rem`, and expand code blocks/tables to `72rem`.

4. In `docs/javascripts/extra.js`:
   - Implement the Focus Mode controller supporting `.nx-focus-btn`, `Z` key to toggle, `Escape` key to exit, input element shielding, and session persistence via `sessionStorage`.
   - Integrate with Material for MkDocs instant-navigation lifecycle via `document$.subscribe()`.

5. Verification:
   - Run `mkdocs build` to confirm an exit code of 0.
   - Verify that all directory carets on the same level share identical horizontal coordinates and that section headers have no arrows.
   - Test laptop auto-collapse between 960px and 1279px.
   - Test Focus Mode via `Z` shortcut, `Escape` shortcut, and session persistence across page transitions.

Please review the repository and implement these changes step by step.