markdowndocs 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75c53c564b04a6a6a957dc2b038121c542e924d97908f5001c100cbca060d3a6
-  data.tar.gz: f791c421dd96c2c81b9bd49019216b72bb796aef43965157e3a608309d25e47d
+  metadata.gz: 6ca89d7b3d1decf28b07cfaccfd1e2e0e0924f8ef7d56d1374e3cb600cbd4933
+  data.tar.gz: 036b99af3190b230d1ceb327171300758b76d09392a4d28b32a9a0129b9cdaf3
 SHA512:
-  metadata.gz: 4af4914a66d3a2bcbdedcfb6e375573897dc1127199c6eabf6b0784f817741fcdb90ba732c4c8f1601bc56eb913781dc89dd59507c18c09ffea490ed211695e3
-  data.tar.gz: 3d733bca1efcdbb749a35491506f0d0f13ac4e7ed1f2f04ea6ee698cd94854cec7791e374ad02211a020a2d1012334639c49c5d87e1adb8b2b531a4f57d39be1
+  metadata.gz: 80f8fb1ad69d4e83407943a1655a7da909d3704ce950ccb3e01a01a515aa3b7a96804e3ae93ceea7ed2cace9497267d750010a2c6fd05b56db27abc89f597432
+  data.tar.gz: 7b7a5ba65d0e5e549811734b03aed0bcc5d52b0c13b768f5e06599162b367998f7d4f7294fe7af2a37d82924ce1826e7e65fbfa39b616bf97828f6b68f83fe2a

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.5

data/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-06-24
+
+### Added
+
+- **Persistent audience switcher.** The viewing-mode switcher now renders in a
+  toolbar at the top of both the docs index and every doc page (new
+  `markdowndocs/docs/_docs_toolbar` partial), instead of only the show-page
+  sidebar — the audience choice is always visible and rendered once per page.
+  `DocsController#index` and `#show` both expose `@available_modes` from
+  `config.modes`.
+- **Screen-reader mode announcement.** Switching audience sets `flash[:notice]`
+  (`markdowndocs.mode_announcement`), surfaced in a `role="status"
+  aria-live="polite"` region in the engine layout so the Turbo-replace mode
+  change isn't silent for assistive tech. Hosts may render the flash their own way.
+
+### Changed
+
+- **No-counterpart audience switch goes to the target index.** Switching to a
+  mode where the current doc has no counterpart (and no shared-root fallback)
+  now redirects to that audience's index — with a distinct flash
+  (`markdowndocs.no_counterpart_announcement`) — instead of stranding the reader
+  on a doc outside the audience they chose. Topic-preserving (scoped counterpart)
+  and shared-root docs are unchanged.
+
+### Fixed
+
+- **Mode switcher ARIA: toggle-button group, not a radiogroup.** Each mode is a
+  submit button using `aria-pressed` (was `role="radio"` / `aria-checked`, which
+  implied unimplemented arrow-key navigation). Focus returns to the chosen button
+  after the Turbo replace.
+
+## [0.9.0] - 2026-06-21
+
+### Added
+
+- **Collapsible disclosure (`<details>` / `<summary>`).** Both tags — plus the
+  `open` attribute — are now in the sanitizer allow-list, so docs can use native,
+  no-JS click-to-expand sections. Rides the same curated raw-HTML passthrough as
+  inline SVG (requires `config.allow_svg = true`, which flips commonmarker to
+  unsafe so the markup reaches the sanitizer). Scripts and `on*` handlers inside
+  a disclosure are still stripped.
+
 ## [0.8.0] - 2026-05-29
 
 ### Added

data/README.md

@@ -118,13 +118,7 @@ Add optional YAML front matter to set metadata:
 ---
 title: "Quick Start Guide"
 description: "Get up and running in five minutes"
-audience:
-  - guide
-  - technical
-modes:
-  - guide
-  - technical
-default_mode: guide
+keywords: [setup, install]
 ---
 
 # Quick Start Guide
@@ -132,6 +126,17 @@ default_mode: guide
 Your content here...
 ```
 
+Recognized keys:
+
+| Key            | Type             | Purpose                                                                          |
+| -------------- | ---------------- | -------------------------------------------------------------------------------- |
+| `title`        | String           | Overrides the H1-derived title shown in nav and `<title>`                        |
+| `description`  | String           | Card description on the index page; defaults to the first paragraph              |
+| `keywords`     | Array of String  | Tags surfaced to the search indexer                                              |
+| `modes`        | Array of String  | Per-doc override of which modes contain block-filtered content (see Mode Blocks) |
+| `default_mode` | String           | Per-doc default mode (overrides `config.default_mode`)                           |
+| `audience`     | String / Array   | **Deprecated.** Use filesystem-path scoping instead — see below                  |
+
 If front matter is omitted, the title is extracted from the first H1 heading and the description from the first paragraph.
 
 ### Audience Filtering by Filesystem Path
@@ -157,12 +162,47 @@ URLs follow the filesystem layout: `app/docs/billing.md` is served at
 Subdirectories whose name does not match a configured mode are ignored
 by document discovery, with a one-line warning at boot.
 
+#### Linking to Docs from Your Host App
+
+The engine exposes two named route helpers under its mount point:
+
+```erb
+<%# Shared (root) doc — /docs/billing %>
+<%= link_to "Billing", markdowndocs.doc_path(slug: "billing") %>
+
+<%# Mode-scoped doc — /docs/technical/architecture %>
+<%= link_to "Architecture",
+            markdowndocs.scoped_doc_path(mode: "technical", slug: "architecture") %>
+```
+
+The `:mode` segment is constrained at the route level; unknown modes
+404 rather than reach the controller.
+
+#### Switching Modes
+
+The mode switcher in the docs UI is *smart* about navigation. When the
+viewer toggles modes, the engine attempts to keep them on the
+equivalent document in the target mode:
+
+- On `/docs/billing` (shared root), switching to `technical` redirects
+  to `/docs/technical/billing` if that scoped sibling exists; otherwise
+  it stays on the shared doc.
+- On `/docs/technical/architecture`, switching to `guide` redirects to
+  `/docs/architecture` if a shared sibling exists; otherwise it stays
+  on the current page.
+- Toggling from the index (`/docs`) just reloads the index in the new
+  mode.
+
+URLs remain stable across the toggle — bookmarks and shared links to
+mode-scoped docs keep working.
+
 ### Audience Filtering by Frontmatter (deprecated)
 
 The `audience:` frontmatter key from v0.6.0 still works in v0.7.x but is
 deprecated. A warning is logged the first time each affected file is
 read. Move the file into the matching mode subdirectory and remove the
-`audience:` key. See the migration guide below.
+`audience:` key — see [Migrating from v0.6.x to v0.7.0](#migrating-from-v06x-to-v070)
+for step-by-step diffs.
 
 ```yaml
 audience: technical          # deprecated — move to app/docs/technical/
@@ -216,6 +256,43 @@ function hello() {
 
 Supported languages include Ruby, JavaScript, Python, Bash, YAML, JSON, HTML, CSS, SQL, and [many more](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers).
 
+### Inline SVG (Hand-Authored Diagrams)
+
+Set `config.allow_svg = true` to opt into a curated, safe subset of inline
+SVG for diagrams written directly in markdown. The sanitizer remains the
+security boundary: `<script>`, `<foreignObject>`, `on*` event handlers, and
+`javascript:` URIs are always stripped, regardless of this setting.
+
+Allowed structural elements: `svg g path rect circle ellipse line polyline
+polygon text tspan defs marker desc`.
+
+#### Giving an SVG an accessible name
+
+Inline SVGs need an accessible name so screen readers can announce them.
+Use `role="img"` plus `aria-label`, or pair the SVG with a `<desc>` and
+`aria-describedby`:
+
+```html
+<svg role="img" aria-label="High-level system architecture"
+     viewBox="0 0 100 100">
+  …
+</svg>
+
+<svg role="img" aria-labelledby="t1" aria-describedby="d1"
+     viewBox="0 0 100 100">
+  <desc id="d1">Three-tier diagram: browser → Rails → Postgres.</desc>
+  …
+</svg>
+```
+
+Decorative SVGs (icons, dividers) should be marked `aria-hidden="true"`
+so assistive technology skips them.
+
+> The `<title>` SVG element is intentionally NOT in the safelist: the
+> HTML5 parser treats it as a raw-text element in HTML context, so the
+> name would silently escape into surrounding text. `aria-label` is the
+> reliable path.
+
 ### Categories
 
 To organize docs on the index page, map category names to slugs in your configuration:

data/app/assets/javascripts/markdowndocs/controllers/docs_mode_controller.js

@@ -16,11 +16,45 @@ export default class extends Controller {
   }
 
   static STORAGE_KEY = "markdowndocs_mode"
+  static FOCUS_KEY = "markdowndocs_focus_mode"
 
   connect() {
     if (!this.isAuthenticated()) {
       this.restoreGuestMode()
     }
+    this.restoreFocusAfterToggle()
+  }
+
+  rememberFocus(event) {
+    // Save the mode the user just pressed so we can restore focus to the
+    // matching button after Turbo replaces the page (a11y: keep focus on
+    // the control the user actuated, not on the article wrapper).
+    try {
+      const mode = event.currentTarget.dataset.mode
+      if (mode) {
+        sessionStorage.setItem(this.constructor.FOCUS_KEY, mode)
+      }
+    } catch (e) {
+      // sessionStorage unavailable — accept the focus loss gracefully.
+    }
+  }
+
+  restoreFocusAfterToggle() {
+    let pendingMode
+    try {
+      pendingMode = sessionStorage.getItem(this.constructor.FOCUS_KEY)
+      if (pendingMode) sessionStorage.removeItem(this.constructor.FOCUS_KEY)
+    } catch (e) {
+      return
+    }
+    if (!pendingMode) return
+
+    const button = this.element.querySelector(`button[data-mode="${pendingMode}"]`)
+    if (button) {
+      // Defer past the Turbo render + autofocus on the article wrapper so
+      // we steal focus from it; otherwise autofocus would win the race.
+      window.requestAnimationFrame(() => button.focus())
+    }
   }
 
   isAuthenticated() {

data/app/controllers/markdowndocs/docs_controller.rb

@@ -14,6 +14,7 @@ module Markdowndocs
       # surviving docs are dropped (see Documentation.grouped_by_category).
       @docs_by_category = Documentation.grouped_by_category(mode: @docs_mode)
       @search_enabled = Markdowndocs.config.search_enabled
+      @available_modes = Markdowndocs.config.modes
     end
 
     def search_index
@@ -64,7 +65,7 @@ module Markdowndocs
       )
       @rendered_content = helpers.add_heading_anchors(rendered_html)
       @related_docs = Documentation.by_category(@doc.category).reject { |d| d.path_slug == @doc.path_slug }
-      @available_modes = @doc.available_modes
+      @available_modes = Markdowndocs.config.modes
       @toc_items = helpers.generate_table_of_contents(@rendered_content)
     end
 

data/app/controllers/markdowndocs/preferences_controller.rb

@@ -25,7 +25,25 @@ module Markdowndocs
         httponly: true
       }
 
-      redirect_to(smart_nav_target(mode, params[:current_path]), status: :see_other)
+      current_path = params[:current_path]
+      target = smart_nav_target(mode, current_path)
+      mode_name = I18n.t("markdowndocs.modes.#{mode}", default: mode.titleize)
+
+      flash[:notice] = if redirected_to_index_from_doc?(target, current_path)
+        I18n.t(
+          "markdowndocs.no_counterpart_announcement",
+          mode: mode_name,
+          default: "No %{mode} version of this page — showing the %{mode} documentation."
+        )
+      else
+        I18n.t(
+          "markdowndocs.mode_announcement",
+          mode: mode_name,
+          default: "Now viewing %{mode}."
+        )
+      end
+
+      redirect_to(target, status: :see_other)
     end
 
     private
@@ -43,22 +61,47 @@ module Markdowndocs
       slug = extract_slug_from_path(current_path)
       return index_path if slug.nil?
 
-      docs_path = Markdowndocs.config.resolved_docs_path
-      scoped_file = docs_path.join(target_mode, "#{slug}.md")
-      root_file = docs_path.join("#{slug}.md")
-
       scoped_url = markdowndocs.scoped_doc_path(mode: target_mode, slug: slug)
       root_url = markdowndocs.doc_path(slug: slug)
 
-      if scoped_file.exist? && current_path != scoped_url
+      # Use Documentation.find_by_slug for existence so symlink-escape
+      # rejection (and any other reachability rules) match what the show
+      # action would actually serve. Bypassing this — e.g. with raw
+      # File.exist? — can redirect the user into a 404.
+      if scoped_sibling_reachable?(slug, target_mode)
         scoped_url
-      elsif root_file.exist? && current_path != root_url
+      elsif root_sibling_reachable?(slug)
         root_url
       else
-        current_path
+        # No counterpart in the target mode and no shared root fallback: send the
+        # reader to that audience's index rather than stranding them on a doc
+        # outside the audience they just chose.
+        index_path
       end
     end
 
+    # True when the switch had to fall back to the docs index because the current
+    # doc has no counterpart in the target mode (selects the flash copy below).
+    def redirected_to_index_from_doc?(target, current_path)
+      current_path.present? &&
+        target == markdowndocs.root_path.chomp("/") &&
+        extract_slug_from_path(current_path).present?
+    end
+
+    def scoped_sibling_reachable?(slug, target_mode)
+      docs_path = Markdowndocs.config.resolved_docs_path
+      scoped_file = docs_path.join(target_mode, "#{slug}.md")
+      return false unless scoped_file.exist?
+      Documentation.inside_docs_path?(scoped_file, docs_path.realpath)
+    end
+
+    def root_sibling_reachable?(slug)
+      docs_path = Markdowndocs.config.resolved_docs_path
+      root_file = docs_path.join("#{slug}.md")
+      return false unless root_file.exist?
+      Documentation.inside_docs_path?(root_file, docs_path.realpath)
+    end
+
     # Pulls the slug from a docs path. Returns nil if the path is the index
     # or doesn't match the docs URL shape. Recognizes both /docs/<slug> and
     # /docs/<mode>/<slug>.

data/app/models/markdowndocs/documentation.rb

@@ -19,15 +19,24 @@ module Markdowndocs
       docs_path = Markdowndocs.config.resolved_docs_path
       return [] unless docs_path.exist?
 
+      docs_root_real = docs_path.realpath
+
       files = Dir.glob(docs_path.join("*.md"))
 
       modes = Markdowndocs.config.modes
       modes.each do |mode|
         mode_dir = docs_path.join(mode)
-        files.concat(Dir.glob(mode_dir.join("*.md"))) if mode_dir.exist?
+        next unless mode_dir.exist?
+        next unless inside_docs_path?(mode_dir, docs_root_real)
+        files.concat(Dir.glob(mode_dir.join("*.md")))
+      end
+
+      # Drop symlink-escapes from the merged file list.
+      files = files.select do |f|
+        inside_docs_path?(Pathname.new(f), docs_root_real)
       end
 
-      warn_about_non_mode_subdirectories(docs_path, modes)
+      warn_about_non_mode_subdirectories(docs_path, modes, docs_root_real)
 
       files.map { |f| new(Pathname.new(f)) }.sort_by(&:path_slug)
     end
@@ -36,8 +45,9 @@ module Markdowndocs
     # subdirectory under docs_path that isn't a configured mode. Files
     # inside such subdirectories are silently dropped by discovery —
     # the warning makes that visible.
-    def self.warn_about_non_mode_subdirectories(docs_path, modes)
+    def self.warn_about_non_mode_subdirectories(docs_path, modes, docs_root_real = nil)
       warned = Markdowndocs.config.non_mode_subdirs_warned
+      docs_root_real ||= docs_path.realpath
 
       children = begin
         docs_path.children
@@ -48,6 +58,8 @@ module Markdowndocs
 
       children.each do |child|
         next unless child.directory?
+        # Don't follow symlinked subdirs that escape docs_path.
+        next unless inside_docs_path?(child, docs_root_real)
         name = child.basename.to_s
         next if modes.include?(name)
         next if warned.include?(name)
@@ -92,7 +104,9 @@ module Markdowndocs
 
     # Returns true when file_path resolves (after following symlinks) to a
     # location inside docs_root_real. Defense against symlinks that point
-    # outside the docs tree.
+    # outside the docs tree. Callers outside this class (e.g. smart-nav in
+    # PreferencesController) use this to keep reachability checks aligned
+    # with what the show action would actually serve.
     def self.inside_docs_path?(file_path, docs_root_real)
       resolved = file_path.realpath
       resolved.to_s == docs_root_real.to_s ||
@@ -100,7 +114,6 @@ module Markdowndocs
     rescue Errno::ENOENT, Errno::ELOOP
       false
     end
-    private_class_method :inside_docs_path?
 
     def self.by_category(category)
       all.select { |doc| doc.category == category }

data/app/services/markdowndocs/markdown_renderer.rb

@@ -51,9 +51,19 @@ module Markdowndocs
         html = apply_syntax_highlighting(html)
         sanitize_html(html)
       rescue => e
+        # Bare rescue is intentional: third-party errors from commonmarker,
+        # Gumbo (Nokogiri::HTML5), Rouge, and Loofah are diverse and not
+        # worth enumerating. We never want a single malformed doc — e.g.
+        # a deeply nested inline SVG — to blank-render the page. Logs
+        # carry the diagnostic; the user sees their content as text.
         Rails.logger.error("Markdowndocs::MarkdownRenderer error: #{e.message}")
-        Rails.logger.error(e.backtrace.join("\n"))
-        ""
+        Rails.logger.error(e.backtrace.first(20).join("\n"))
+        render_fallback(markdown)
+      end
+
+      def render_fallback(markdown)
+        escaped = ERB::Util.html_escape(markdown.to_s)
+        %(<pre class="markdowndocs-render-error">#{escaped}</pre>)
       end
 
       def apply_syntax_highlighting(html)
@@ -111,17 +121,35 @@ module Markdowndocs
         a img
         strong em b i u del
         code pre span div
+        details summary
       ].freeze
 
-      BASE_SANITIZE_ATTRS = %w[href title src alt align class lang].freeze
+      # ARIA labelling/role attributes are useful on any element. Adding them
+      # to BASE keeps non-SVG inline HTML accessible too (when allow_svg=true).
+      # No security risk — ARIA attributes carry no executable content.
+      BASE_SANITIZE_ATTRS = %w[
+        href title src alt align class lang
+        role aria-label aria-labelledby aria-describedby aria-hidden
+        open
+      ].freeze
 
       # Curated structural SVG subset. Deliberately excludes script,
       # foreignObject, and SMIL animate/set tags, plus all on* handlers — the
       # SafeListSanitizer drops anything not listed, so scripts/handlers and
       # javascript: URIs are stripped even with unsafe HTML enabled.
+      #
+      # Note: `<title>` is NOT included. Despite appearing safe, the HTML5
+      # parser treats `<title>` as a raw-text element when encountered in
+      # HTML context, so its content escapes into the surrounding text and
+      # the `<title>` element itself is dropped. Authors who want an
+      # accessible name for an inline SVG should use:
+      #
+      #   <svg role="img" aria-label="Architecture diagram">…</svg>
+      #
+      # or pair the SVG with a `<desc>` element and aria-describedby.
       SVG_SANITIZE_TAGS = %w[
         svg g path rect circle ellipse line polyline polygon
-        text tspan defs marker title desc
+        text tspan defs marker desc
       ].freeze
 
       SVG_SANITIZE_ATTRS = %w[
@@ -131,7 +159,7 @@ module Markdowndocs
         transform opacity text-anchor dominant-baseline
         font-size font-family font-weight
         marker-start marker-end markerWidth markerHeight refX refY orient
-        role aria-label id
+        id xmlns focusable tabindex
       ].freeze
 
       def sanitize_html(html)

data/app/views/layouts/markdowndocs/application.html.erb

@@ -11,6 +11,9 @@
   </head>
 
   <body class="min-h-screen flex flex-col bg-gray-50">
+    <% if flash[:notice].present? %>
+      <div role="status" aria-live="polite" class="sr-only"><%= flash[:notice] %></div>
+    <% end %>
     <%= yield :docs_header %>
 
     <main id="main-content" role="main" class="flex-1">

data/app/views/markdowndocs/docs/_docs_toolbar.html.erb

@@ -0,0 +1,10 @@
+<%# locals: (current_mode:, available_modes:) %>
+<%# Persistent docs toolbar: the audience switcher, shown at the top of both
+    the index and every doc page. Renders nothing when only one mode exists. %>
+<% if available_modes.length > 1 %>
+  <div class="flex justify-end mb-6">
+    <%= render "markdowndocs/docs/mode_switcher",
+      current_mode: current_mode,
+      available_modes: available_modes %>
+  </div>
+<% end %>

data/app/views/markdowndocs/docs/_mode_switcher.html.erb

@@ -1,80 +1,29 @@
 <%# locals: (current_mode:, available_modes:) %>
-<%# No `id=` on the root: show.html.erb renders _navigation twice (mobile +
-    desktop sidebars), which embeds this partial twice — a hardcoded id
-    would produce duplicate ids in the DOM (WCAG 4.1.1 violation, see
-    issue #20). Stimulus already scopes itself via data-controller, which
-    can appear N times without colliding. Tests / selectors should target
-    [data-controller="docs-mode"] rather than #docs-mode-switcher. %>
+<%# Horizontal audience toggle for the docs toolbar (rendered once per page).
+    Toggle-button group, NOT a radiogroup: each option is its own form +
+    submit button, so aria-pressed describes state. No element id — tests
+    target [data-controller="docs-mode"]. %>
 <div
-  class="
-    bg-white
-    dark:bg-slate-800
-    rounded-lg
-    border
-    border-slate-200
-    dark:border-slate-700
-    p-4
-  "
+  class="flex items-center gap-2"
   data-controller="docs-mode"
   data-docs-mode-current-value="<%= current_mode %>"
 >
-  <h3 class="
-    text-sm
-    font-medium
-    text-slate-700
-    dark:text-slate-300
-    mb-3
-  ">
+  <span class="text-sm font-medium text-slate-700 dark:text-slate-300">
     <%= t("markdowndocs.viewing_mode") %>
-  </h3>
-
-  <div
-    class="space-y-2"
-    role="radiogroup"
-    aria-label="<%= t('markdowndocs.select_viewing_mode') %>"
-  >
+  </span>
+  <div class="inline-flex gap-1" role="group" aria-label="<%= t('markdowndocs.select_viewing_mode') %>">
     <% available_modes.each do |mode| %>
-      <%= form_with(
-        url: markdowndocs.preference_path,
-        method: :patch,
-        data: {
-          turbo_action: "replace"
-        }
-      ) do |f| %>
+      <%= form_with(url: markdowndocs.preference_path, method: :patch, data: {turbo_action: "replace"}) do |f| %>
         <%= f.hidden_field :mode, value: mode, id: nil %>
         <%= f.hidden_field :current_path, value: request.fullpath, id: nil %>
         <button
           type="submit"
-          role="radio"
-          aria-checked="<%= current_mode == mode %>"
-          class="
-            w-full
-            text-left
-            p-3
-            rounded-lg
-            border-2
-            transition-all
-            duration-150
-            <%= (current_mode == mode) ? 'border-cyan-500 bg-cyan-50 dark:bg-cyan-900/40 dark:border-cyan-400' : 'border-slate-200 hover:border-slate-300 hover:bg-slate-50 dark:border-slate-700 dark:hover:border-slate-500 dark:hover:bg-slate-700' %>
-          "
+          aria-pressed="<%= current_mode == mode %>"
+          data-mode="<%= mode %>"
+          data-action="click->docs-mode#rememberFocus"
+          class="px-3 py-1.5 text-sm font-medium rounded-md border transition-colors <%= (current_mode == mode) ? 'border-cyan-500 bg-cyan-50 text-cyan-900 dark:bg-cyan-900/40 dark:border-cyan-400 dark:text-cyan-100' : 'border-slate-200 text-slate-700 hover:bg-slate-50 dark:border-slate-700 dark:text-slate-300 dark:hover:bg-slate-700' %>"
         >
-          <span class="
-            block
-            font-medium
-            <%= (current_mode == mode) ? 'text-cyan-900 dark:text-cyan-100' : 'text-slate-900 dark:text-slate-100' %>
-          ">
-            <%= t("markdowndocs.modes.#{mode}", default: mode.titleize) %>
-          </span>
-          <% description = t("markdowndocs.modes.#{mode}_description", default: "") %>
-          <% if description.present? %>
-            <p class="
-              text-xs
-              mt-1
-              <%= (current_mode == mode) ? 'text-cyan-900 dark:text-cyan-100' : 'text-slate-700 dark:text-slate-300' %>
-            ">
-              <%= description %>
-            </p>
-          <% end %>
+          <%= t("markdowndocs.modes.#{mode}", default: mode.titleize) %>
         </button>
       <% end %>
     <% end %>

data/app/views/markdowndocs/docs/_navigation.html.erb

@@ -1,11 +1,5 @@
-<%# locals: (rendered_content:, related_docs:, current_mode:, available_modes:, toc_items:) %>
+<%# locals: (rendered_content:, related_docs:, toc_items:) %>
 <aside class="sidebar space-y-6">
-  <% if available_modes.length > 1 %>
-    <%= render "markdowndocs/docs/mode_switcher",
-      current_mode: current_mode,
-      available_modes: available_modes %>
-  <% end %>
-
   <% if toc_items.length >= 3 %>
     <div class="bg-white dark:bg-slate-800 rounded-lg shadow-sm p-6">
       <nav aria-label="Table of Contents">

data/app/views/markdowndocs/docs/index.html.erb

@@ -6,6 +6,9 @@
        data-controller="docs-search"
        data-docs-search-index-url-value="<%= markdowndocs.search_index_path %>"
     <% end %>>
+    <%= render "markdowndocs/docs/docs_toolbar",
+      current_mode: @docs_mode,
+      available_modes: @available_modes %>
     <!-- Hero Section -->
     <div class="text-center mb-12">
       <h1 class="text-4xl font-bold text-gray-900 dark:text-slate-100 mb-4">Documentation</h1>

data/app/views/markdowndocs/docs/show.html.erb

@@ -18,6 +18,10 @@
     <!-- Breadcrumb -->
     <%= render "markdowndocs/docs/breadcrumb", category: @doc.category, title: @doc.title %>
 
+    <%= render "markdowndocs/docs/docs_toolbar",
+      current_mode: @docs_mode,
+      available_modes: @available_modes %>
+
     <!-- Mobile navigation (hamburger dropdown, hidden on desktop) -->
     <div class="lg:hidden mb-6">
       <button
@@ -57,8 +61,6 @@
         <%= render "markdowndocs/docs/navigation",
           rendered_content: @rendered_content,
           related_docs: @related_docs,
-          current_mode: @docs_mode,
-          available_modes: @available_modes,
           toc_items: @toc_items %>
       </div>
     </div>
@@ -84,8 +86,6 @@
           <%= render "markdowndocs/docs/navigation",
             rendered_content: @rendered_content,
             related_docs: @related_docs,
-            current_mode: @docs_mode,
-            available_modes: @available_modes,
             toc_items: @toc_items %>
         </div>
       </div>

data/config/locales/en.yml

@@ -4,6 +4,8 @@ en:
     navigation_sidebar: "Navigation & Related Docs"
     viewing_mode: "Viewing Mode"
     select_viewing_mode: "Select documentation viewing mode"
+    mode_announcement: "Now viewing %{mode}."
+    no_counterpart_announcement: "No %{mode} version of this page — showing the %{mode} documentation."
     modes:
       guide: "User Guide"
       guide_description: "User-friendly explanations and step-by-step instructions"