markdowndocs 0.6.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 834e28ea5348dcb63b8e7c5f952baa34d72166958da926627e16e8c3d1c300e8
-  data.tar.gz: 7cae90fb66f75bf05e14ef61189ab5663e655459a55dc914c9187341af715046
+  metadata.gz: 764b5150885d6a306eae6d49fbabd8dedee96dffa9bc55a6f290da57e3b53123
+  data.tar.gz: 2a75805e06c5caa6fcdbf8e4860836bcf886fc5453b4d394761f8f45ae8ba114
 SHA512:
-  metadata.gz: 43e73ace730900362729bc27b4d086cfac1ba6416d1270df6c52ed1ae40bceccd04cde503c0ae29cc1edd4bb890472ec5c9a8877cbf3bd2307d17d66413eb463
-  data.tar.gz: 9d787524af79383f2a77c9c7c1a0bce5c18070a1ab9c46c7ae94fe32c2aa728d15f4f8f7741f14c751edc4ae3c84c9e20a3478d1d668eebc8beb3c12784592e5
+  metadata.gz: 8502ba23be6b2ccafa8abc6f0388fddfaf1eae79da276b2ec676087195f04ddc000c576b636c5f81473c10fe30f2786faa9fa7b901419a3f8689226d6440a86e
+  data.tar.gz: 0d71e8284d7a5ed9efcdd8841e0a7e760bb26906e4ac61fb27a1ec32e259357c920e6b86ff66bc16e7d3fdda632c2ed5c12b216ff2b71c1f025f3f1ab73aab99

data/CHANGELOG.md

@@ -5,6 +5,102 @@ 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.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
+
+- **Opt-in inline SVG (`config.allow_svg`).** When set to `true`, a curated,
+  safe subset of structural SVG tags and attributes is permitted in rendered
+  documents — useful for hand-authored diagrams. The `Rails::HTML5`
+  SafeListSanitizer remains the security boundary: `<script>`,
+  `<foreignObject>`, `on*` event handlers, and `javascript:` URIs are still
+  stripped. Defaults to `false`, so existing behavior is unchanged.
+
+### Fixed
+
+- Heading-anchor injection, table-of-contents extraction, and syntax
+  highlighting now parse with `Nokogiri::HTML5` instead of `Nokogiri::HTML`,
+  preserving case-sensitive SVG/MathML foreign-content attributes (e.g.
+  `viewBox`, `markerWidth`, `refX`) that were previously lowercased on
+  re-serialization, which silently broke any inline SVG.
+
+## [0.7.0] - 2026-05-15
+
+### Added
+
+- **Path-based audience routing.** A first-level subdirectory of
+  `app/docs/` whose name matches an entry in `config.modes` is now
+  treated as an audience scope. Files inside `app/docs/technical/` are
+  visible only when the current mode is `technical`; files at the root
+  remain shared (visible in every mode). The new convention is the
+  recommended way to scope whole documents and replaces `audience:`
+  frontmatter (see Deprecated below).
+- **`/docs/:mode/:slug` route.** Mode-scoped documents are served at
+  stable, RESTful URLs (e.g., `/docs/technical/architecture`). The
+  `:mode` segment is constrained to entries in `config.modes`; unknown
+  modes return 404.
+- **Path-prefixed slugs in `config.categories`.** Slug entries may now
+  include a mode prefix (e.g., `"technical/architecture"`) to attach a
+  mode-scoped doc to a category. Bare slugs continue to match root
+  files. Example:
+
+      config.categories = {
+        "Architecture" => %w[technical/architecture]
+      }
+
+- **Smart navigation in mode switcher.** Toggling the mode now attempts
+  to navigate to a same-slug document in the target mode's location,
+  falling back to the shared root sibling, then staying put. Sharing
+  links still works because URLs are stable.
+- **`Markdowndocs.deprecator`** ActiveSupport::Deprecation instance for
+  emitting gem-specific deprecation warnings. Hosts can configure
+  behavior (silence / raise / log) via standard
+  `ActiveSupport::Deprecation` APIs.
+
+### Changed
+
+- `Documentation.all` walks both `app/docs/*.md` and
+  `app/docs/<mode>/*.md` for every configured mode.
+- `Documentation` instances expose `#path_slug` (the file's path
+  relative to the docs root, sans `.md`).
+- `Documentation.find_by_slug(slug, mode:)` prefers the mode-scoped
+  file first, then falls back to the root.
+- `PreferencesController#update` now expects a `current_path` form
+  field (added in `_mode_switcher.html.erb`) and computes the smart-nav
+  target before redirecting. Hosts with custom forms targeting
+  `preference_path` should include `<input type="hidden"
+  name="current_path" value="<%= request.fullpath %>">` to opt into
+  smart navigation. Without it, the controller redirects to the docs
+  index (no behavior loss, just no smart-nav benefit).
+
+### Deprecated
+
+- **`audience:` frontmatter.** Still functional, but emits a one-shot
+  warning per file path per process boot. Will be removed in v1.0.0.
+  Migration: move the file into a matching mode subdirectory (or, for
+  multi-audience docs, drop the key — root files are shared). The
+  warning message includes the suggested target path.
+
+### Migration notes
+
+- See `README.md` ("Migrating from v0.6.x to v0.7.0") for full guidance.
+- URL stability: every URL from v0.6.x continues to resolve unchanged.
+- Subdirectories under `app/docs/` whose name doesn't match a
+  configured mode are now ignored (one-line warning at discovery). If
+  you've been using non-mode subdirectories for organization, either
+  flatten them or rename them to match a configured mode.
+
 ## [0.6.1] - 2026-05-13
 
 ### Fixed
@@ -194,6 +290,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - i18n support for all UI strings
 - Install generator (`rails generate markdowndocs:install`)
 
+[0.7.0]: https://github.com/dschmura/markdowndocs/releases/tag/v0.7.0
+[0.6.1]: https://github.com/dschmura/markdowndocs/releases/tag/v0.6.1
+[0.6.0]: https://github.com/dschmura/markdowndocs/releases/tag/v0.6.0
 [0.5.0]: https://github.com/dschmura/markdowndocs/releases/tag/v0.5.0
 [0.4.0]: https://github.com/dschmura/markdowndocs/releases/tag/v0.4.0
 [0.3.1]: https://github.com/dschmura/markdowndocs/releases/tag/v0.3.1

data/README.md

@@ -55,8 +55,8 @@ Markdowndocs.configure do |config|
   # Category → slug mapping
   config.categories = {
     "Getting Started" => %w[welcome quickstart],
-    "Guides" => %w[authentication deployment],
-    "Reference" => %w[api-reference configuration]
+    "Guides" => %w[authentication billing],
+    "Architecture" => %w[technical/architecture technical/billing]
   }
 
   # Available documentation modes (default: %w[guide technical])
@@ -71,6 +71,11 @@ Markdowndocs.configure do |config|
   # Cache expiry for rendered markdown (default: 1.hour)
   # config.cache_expiry = 1.hour
 
+  # Allow a curated, safe subset of inline SVG (for hand-authored diagrams).
+  # Scripts, event handlers, and javascript: URIs are still stripped by the
+  # sanitizer. Default: false. (default: false)
+  # config.allow_svg = true
+
   # Optional: Resolve current user's mode preference from database
   # config.user_mode_resolver = ->(controller) {
   #   controller.send(:current_user)&.preferences&.docs_mode
@@ -83,6 +88,11 @@ Markdowndocs.configure do |config|
 end
 ```
 
+> Bare slugs (e.g., `"welcome"`) match files at the docs root.
+> Path-prefixed slugs (e.g., `"technical/architecture"`) match files
+> inside the named mode subdirectory. The prefix segment must match
+> an entry in `config.modes`.
+
 ### Configuration Options
 
 | Option               | Default                        | Description                                                    |
@@ -108,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
@@ -122,25 +126,91 @@ 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 (whole-document)
+### Audience Filtering by Filesystem Path
+
+The recommended way to scope a whole document to a single audience is to
+place it inside a subdirectory whose name matches an entry in
+`config.modes`. Files at the docs root are *shared* — visible in every
+mode.
+
+```text
+app/docs/
+├── getting_started.md         → shared, visible in every mode
+├── billing.md                 → shared
+└── technical/
+    ├── architecture.md        → technical mode only
+    └── billing.md             → technical mode only
+```
 
-For content that's split into separate files per audience (a user guide
-and a deep-dive technical reference, for example), use the `audience:`
-key in front matter to declare who a doc is for:
+URLs follow the filesystem layout: `app/docs/billing.md` is served at
+`/docs/billing`; `app/docs/technical/billing.md` is served at
+`/docs/technical/billing`. Both URLs are stable and shareable.
+
+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 [Migrating from v0.6.x to v0.7.0](#migrating-from-v06x-to-v070)
+for step-by-step diffs.
 
 ```yaml
-audience: technical          # single-audience: shown only when mode=technical
-audience: [guide, technical] # multi-audience: shown in either mode
-# omit `audience:`           # backward-compatible: shown in every mode
+audience: technical          # deprecated — move to app/docs/technical/
+audience: [guide, technical] # deprecated — keep at root, drop the key
+# omit `audience:`           # still works for shared docs at root
 ```
 
-When the current mode does not appear in a doc's audience, the doc is
-hidden from the index AND unreachable via slug (404). This complements
-the in-page `<!-- mode: -->` blocks below: use mode blocks when one doc
-mixes audience-specific snippets; use `audience:` when whole docs are
-audience-specific.
+The `audience:` key is scheduled for removal in v1.0.0.
 
 ### Mode Blocks
 
@@ -186,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:
@@ -303,6 +410,57 @@ bundle exec rspec
 
    Pushing the tag triggers the GitHub Actions release workflow, which builds and publishes the gem to RubyGems automatically.
 
+## Migrating from v0.6.x to v0.7.0
+
+**URL stability.** Every URL from v0.6.x continues to resolve. Hosts
+that upgrade without moving files see zero URL changes. Path-based
+routing only introduces *new* URLs (`/docs/<mode>/<slug>`) when you
+explicitly relocate files into mode subdirectories.
+
+### If you don't use `audience:` today
+
+No action required. Adopt the new convention at your leisure.
+
+### If you use `audience: <single-mode>`
+
+For each affected doc:
+
+```diff
+- app/docs/foo.md
+- ---
+- audience: technical
+- ---
++ app/docs/technical/foo.md
++ (no `audience:` key)
+```
+
+The deprecation warning surfaces the suggested target path.
+
+### If you use `audience: [guide, technical]`
+
+The doc is multi-audience — drop the key, the root file is shared:
+
+```diff
+  app/docs/foo.md
+- ---
+- audience: [guide, technical]
+- ---
++ (no `audience:` key)
+```
+
+### `config.categories` for mode-scoped docs
+
+Prefix slugs with the mode subdirectory:
+
+```diff
+  config.categories = {
+-   "Architecture" => %w[architecture data_model]
++   "Architecture" => %w[technical/architecture data_model]
+  }
+```
+
+Bare slugs continue to mean "the doc at the root with this name."
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [github.com/dschmura/markdowndocs](https://github.com/dschmura/markdowndocs).

data/app/controllers/markdowndocs/docs_controller.rb

@@ -26,7 +26,7 @@ module Markdowndocs
       json = Rails.cache.fetch(cache_key, expires_in: Markdowndocs.config.cache_expiry) do
         Documentation.all.map do |doc|
           {
-            id: doc.slug,
+            id: doc.path_slug,
             title: doc.title,
             description: doc.description,
             content: doc.plain_text_content,
@@ -41,25 +41,29 @@ module Markdowndocs
     end
 
     def show
-      # Audience filter: a doc with `audience: technical` is unreachable
-      # via slug while the user is in guide mode — they get the 404 page,
-      # not the doc's content. This matters because the index already
-      # hides those docs; making the show route honor the same filter
-      # keeps URL guessing / shared-link scenarios consistent.
-      @doc = Documentation.find_by_slug(params[:slug], mode: @docs_mode)
+      # `params[:mode]` here is the URL path segment (e.g. /docs/technical/foo → "technical")
+      # if the request matched the scoped route. Otherwise, fall back to the resolved
+      # current preference (@docs_mode) so root-mounted docs honor audience-frontmatter
+      # filtering.
+      lookup_mode = params[:mode].presence || @docs_mode
+      @doc = Documentation.find_by_slug(params[:slug], mode: lookup_mode)
 
       if @doc.nil?
         render_not_found
         return
       end
 
+      # `mode:` here controls in-doc <!-- mode: X --> block stripping,
+      # which should reflect the user's PREFERENCE (@docs_mode), not the
+      # URL-path mode (lookup_mode). A /technical/foo URL does not force
+      # guide-only blocks invisible.
       rendered_html = MarkdownRenderer.render(
         @doc.content,
         cache_key: @doc.cache_key,
         mode: @docs_mode
       )
       @rendered_content = helpers.add_heading_anchors(rendered_html)
-      @related_docs = Documentation.by_category(@doc.category).reject { |d| d.slug == @doc.slug }
+      @related_docs = Documentation.by_category(@doc.category).reject { |d| d.path_slug == @doc.path_slug }
       @available_modes = @doc.available_modes
       @toc_items = helpers.generate_table_of_contents(@rendered_content)
     end
@@ -88,7 +92,17 @@ module Markdowndocs
     end
 
     def determine_docs_mode
-      mode = params[:mode] ||
+      # Only treat params[:mode] as a preference override on the root-mounted
+      # `/:slug` route. On the scoped `/:mode/:slug` route, params[:mode] is
+      # the URL path segment and is consumed by `show` for doc lookup, not as
+      # a preference override.
+      preference_param = if path_mode_in_request?
+        nil
+      else
+        params[:mode]
+      end
+
+      mode = preference_param ||
         resolve_user_mode ||
         cookies[:markdowndocs_mode] ||
         Markdowndocs.config.default_mode
@@ -97,6 +111,12 @@ module Markdowndocs
       valid_modes.include?(mode) ? mode : Markdowndocs.config.default_mode
     end
 
+    def path_mode_in_request?
+      # The scoped route names `mode` as a path param. On the unscoped route,
+      # `mode` (when present) comes from the query string.
+      request.path_parameters[:mode].present?
+    end
+
     def resolve_user_mode
       resolver = Markdowndocs.config.user_mode_resolver
       return nil unless resolver.respond_to?(:call)

data/app/controllers/markdowndocs/preferences_controller.rb

@@ -10,7 +10,6 @@ module Markdowndocs
         return
       end
 
-      # Save to database via host app's lambda (if configured)
       saver = Markdowndocs.config.user_mode_saver
       if saver.respond_to?(:call)
         begin
@@ -20,14 +19,88 @@ module Markdowndocs
         end
       end
 
-      # Always set cookie as fallback
       cookies[:markdowndocs_mode] = {
         value: mode,
         expires: 1.year.from_now,
         httponly: true
       }
 
-      redirect_back(fallback_location: markdowndocs.root_path, status: :see_other)
+      redirect_to(smart_nav_target(mode, params[:current_path]), status: :see_other)
+    end
+
+    private
+
+    # Computes the post-toggle destination using the unified lookup rule:
+    #   1. /docs/<target_mode>/<slug> if the scoped file exists and is not current
+    #   2. /docs/<slug> (root) if it exists and is not current
+    #   3. current path (stay put)
+    # Falls back to the docs index when current_path is missing or doesn't
+    # match a recognizable doc URL.
+    def smart_nav_target(target_mode, current_path)
+      index_path = markdowndocs.root_path.chomp("/")
+      return index_path if current_path.blank?
+
+      slug = extract_slug_from_path(current_path)
+      return index_path if slug.nil?
+
+      scoped_url = markdowndocs.scoped_doc_path(mode: target_mode, slug: slug)
+      root_url = markdowndocs.doc_path(slug: slug)
+
+      # 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) && current_path != scoped_url
+        scoped_url
+      elsif root_sibling_reachable?(slug) && current_path != root_url
+        root_url
+      else
+        current_path
+      end
+    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>.
+    def extract_slug_from_path(path)
+      # Strip query string and trailing slash.
+      clean = path.split("?").first.to_s.chomp("/")
+      base = markdowndocs.root_path.chomp("/")
+      return nil unless clean.start_with?(base)
+
+      remainder = clean[base.length..]
+      return nil if remainder.blank? || remainder == "/"
+
+      segments = remainder.sub(%r{\A/}, "").split("/")
+
+      case segments.length
+      when 1
+        slug_candidate(segments.first)
+      when 2
+        # Could be /<mode>/<slug>. Only treat second segment as the slug
+        # if the first is a configured mode.
+        Markdowndocs.config.modes.include?(segments.first) ? slug_candidate(segments.last) : nil
+      end
+    end
+
+    def slug_candidate(segment)
+      return nil if segment.blank?
+      return nil if segment.include?("..") || segment.include?("/")
+      segment
     end
   end
 end

data/app/helpers/markdowndocs/docs_helper.rb

@@ -5,7 +5,9 @@ module Markdowndocs
     def generate_table_of_contents(html)
       return [] if html.blank?
 
-      doc = Nokogiri::HTML.fragment(html)
+      # HTML5 parsing preserves case-sensitive foreign-content (SVG/MathML)
+      # attributes like viewBox/markerWidth; Nokogiri::HTML lowercases them.
+      doc = Nokogiri::HTML5.fragment(html)
       toc_items = []
 
       doc.css("h2, h3").each do |heading|
@@ -35,7 +37,9 @@ module Markdowndocs
     def add_heading_anchors(html)
       return html if html.blank?
 
-      doc = Nokogiri::HTML.fragment(html)
+      # HTML5 parsing preserves case-sensitive foreign-content (SVG/MathML)
+      # attributes like viewBox/markerWidth; Nokogiri::HTML lowercases them.
+      doc = Nokogiri::HTML5.fragment(html)
 
       doc.css("h2, h3").each do |heading|
         text = heading.text.strip

data/app/models/markdowndocs/documentation.rb

@@ -5,11 +5,12 @@ module Markdowndocs
   # Represents markdown documentation files from a configurable directory.
   # Handles metadata extraction, frontmatter parsing, and category associations.
   class Documentation
-    attr_reader :slug, :title, :description, :category, :file_path, :keywords
+    attr_reader :slug, :path_slug, :title, :description, :category, :file_path, :keywords
 
     def initialize(file_path)
       @file_path = file_path
       @slug = derive_slug
+      @path_slug = derive_path_slug
       extract_metadata
       @category = assign_category
     end
@@ -18,23 +19,81 @@ module Markdowndocs
       docs_path = Markdowndocs.config.resolved_docs_path
       return [] unless docs_path.exist?
 
-      Dir.glob(docs_path.join("*.md")).map do |file|
-        new(Pathname.new(file))
-      end.sort_by(&:slug)
+      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)
+        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, docs_root_real)
+
+      files.map { |f| new(Pathname.new(f)) }.sort_by(&:path_slug)
     end
 
-    # When `mode:` is given (e.g. "guide" / "technical"), returns nil if
-    # the resolved doc's `audience:` frontmatter excludes that mode. Docs
-    # without an explicit `audience:` key default to "visible in all modes"
-    # — backward compatible with pre-0.6 docs.
+    # Emits a one-shot warning per process boot for each first-level
+    # 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, docs_root_real = nil)
+      warned = Markdowndocs.config.non_mode_subdirs_warned
+      docs_root_real ||= docs_path.realpath
+
+      children = begin
+        docs_path.children
+      rescue Errno::ENOENT, Errno::EACCES => e
+        Rails.logger.warn("[Markdowndocs] Could not scan for non-mode subdirectories: #{e.message}")
+        return
+      end
+
+      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)
+
+        warned << name
+        Rails.logger.warn(
+          "[Markdowndocs] Ignoring subdirectory #{child}/ — name does not match " \
+          "any configured mode (config.modes = #{modes.inspect}). Files inside " \
+          "this subdirectory will not be discovered. Move them into #{docs_path}/ " \
+          "or into a mode-named subdirectory."
+        )
+      end
+    end
+    private_class_method :warn_about_non_mode_subdirectories
+
+    # Resolves a doc by slug. When `mode:` is given, prefers the mode-scoped
+    # file (docs/<mode>/<slug>.md) and falls back to the root (docs/<slug>.md)
+    # if visible_to?(mode) passes. With `mode: nil`, only the root is checked.
     def self.find_by_slug(slug, mode: nil)
       return nil if slug.blank?
       return nil if slug.include?("..") || slug.include?("/")
 
-      file_path = Markdowndocs.config.resolved_docs_path.join("#{slug}.md")
-      return nil unless file_path.exist?
+      docs_path = Markdowndocs.config.resolved_docs_path
+      docs_root_real = docs_path.realpath
+
+      if mode.present? && Markdowndocs.config.modes.include?(mode.to_s)
+        scoped = docs_path.join(mode.to_s, "#{slug}.md")
+        return new(scoped) if scoped.exist? && inside_docs_path?(scoped, docs_root_real)
+      end
 
-      doc = new(file_path)
+      root = docs_path.join("#{slug}.md")
+      return nil unless root.exist? && inside_docs_path?(root, docs_root_real)
+
+      doc = new(root)
       return nil unless doc.visible_to?(mode)
 
       doc
@@ -43,6 +102,19 @@ module Markdowndocs
       nil
     end
 
+    # 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. 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 ||
+        resolved.to_s.start_with?(docs_root_real.to_s + File::SEPARATOR)
+    rescue Errno::ENOENT, Errno::ELOOP
+      false
+    end
+
     def self.by_category(category)
       all.select { |doc| doc.category == category }
     end
@@ -50,9 +122,17 @@ module Markdowndocs
     # When `mode:` is given, filters out docs whose `audience:` excludes
     # that mode AND drops categories that end up empty (so the index
     # sidebar doesn't render headers with no children).
+    #
+    # Resolves slugs by matching against `path_slug` on the full discovered
+    # set so that path-prefixed slugs like "technical/architecture" (which
+    # `find_by_slug` rejects as directory traversal) are found correctly.
     def self.grouped_by_category(mode: nil)
+      all_docs = all
       Markdowndocs.config.categories.each_with_object({}) do |(category, slugs), hash|
-        docs = slugs.map { |slug| find_by_slug(slug, mode: mode) }.compact
+        docs = slugs.filter_map do |slug|
+          doc = all_docs.find { |d| d.path_slug == slug }
+          doc if doc&.visible_to?(mode)
+        end
         hash[category] = docs unless docs.empty?
       end
     end
@@ -65,7 +145,7 @@ module Markdowndocs
     end
 
     def cache_key
-      "#{slug}-#{mtime.to_i}"
+      "#{path_slug.tr("/", "-")}-#{mtime.to_i}"
     end
 
     def mtime
@@ -94,19 +174,25 @@ module Markdowndocs
       available_modes.include?(mode.to_s)
     end
 
-    # The audience(s) this doc is written for, declared via `audience:`
-    # frontmatter. Accepts a single string or an array; both are coerced
-    # to an Array<String>. When the frontmatter key is missing, defaults
-    # to all configured modes — a doc with no audience declaration is
-    # visible in every mode (backward compat with pre-0.6 docs).
+    # The audience(s) this doc is written for. Resolution order:
+    #   1. `audience:` frontmatter (DEPRECATED in 0.7.0, removed in 1.0.0)
+    #   2. Parent directory name when it matches a configured mode
+    #   3. All configured modes (root file with no override — visible everywhere)
     def audience
       @audience ||= begin
         parsed = parse_frontmatter
         raw = parsed[:frontmatter]["audience"]
+
+        if raw
+          emit_audience_deprecation_warning_once
+        end
+
         case raw
         when Array then raw.map(&:to_s)
         when String then [raw]
-        when nil then Markdowndocs.config.modes.dup
+        when nil
+          scope = audience_from_path
+          scope ? [scope] : Markdowndocs.config.modes.dup
         else Markdowndocs.config.modes.dup
         end
       end
@@ -148,6 +234,49 @@ module Markdowndocs
       file_path.basename(".md").to_s
     end
 
+    def derive_path_slug
+      docs_root = Markdowndocs.config.resolved_docs_path
+      relative = file_path.relative_path_from(docs_root)
+      relative.sub_ext("").to_s
+    end
+
+    def audience_from_path
+      dir = file_path.dirname.basename.to_s
+      Markdowndocs.config.modes.include?(dir) ? dir : nil
+    end
+
+    def emit_audience_deprecation_warning_once
+      path_str = file_path.to_s
+      emitted = Markdowndocs.config.audience_deprecation_emitted
+      return if emitted.include?(path_str)
+
+      emitted << path_str
+
+      Markdowndocs.deprecator.warn(
+        "`audience:` frontmatter in #{path_str} is deprecated. " \
+        "#{suggest_migration_target} The `audience:` key will be removed in v1.0.0."
+      )
+    end
+
+    def suggest_migration_target
+      parsed = parse_frontmatter
+      raw = parsed[:frontmatter]["audience"]
+
+      case raw
+      when String
+        "Move the file to #{file_path.dirname.join(raw, file_path.basename)} instead and remove the `audience:` key."
+      when Array
+        if Array(raw).map(&:to_s).sort == Markdowndocs.config.modes.sort
+          "This doc is already declared multi-audience; remove the `audience:` key (root files are visible in every mode)."
+        else
+          modes = Array(raw).map(&:to_s).join(", ")
+          "This doc declares audience: [#{modes}]. Path-based routing supports only a single mode per file; either move the file to a single mode subdirectory or leave the file at root and remove `audience:` (root is shared)."
+        end
+      else
+        "Move the file into the mode-named subdirectory matching its audience, or leave it at root and remove the key."
+      end
+    end
+
     def extract_metadata
       parsed = parse_frontmatter
 
@@ -227,7 +356,7 @@ module Markdowndocs
 
     def assign_category
       Markdowndocs.config.categories.each do |category, slugs|
-        return category if slugs.include?(slug)
+        return category if slugs.include?(path_slug)
       end
 
       "Other"

data/app/services/markdowndocs/markdown_renderer.rb

@@ -45,18 +45,31 @@ module Markdowndocs
       end
 
       def render_markdown(markdown)
-        doc = Commonmarker.parse(markdown, options: Markdowndocs.config.markdown_options)
-        html = doc.to_html(options: Markdowndocs.config.markdown_options)
+        options = markdown_render_options
+        doc = Commonmarker.parse(markdown, options: options)
+        html = doc.to_html(options: options)
         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)
-        doc = Nokogiri::HTML.fragment(html)
+        # HTML5 parsing preserves case-sensitive SVG/MathML foreign-content
+        # attributes (e.g. viewBox) that Nokogiri::HTML would lowercase.
+        doc = Nokogiri::HTML5.fragment(html)
 
         doc.css("pre[lang]").each do |pre|
           language = pre["lang"]
@@ -91,25 +104,71 @@ module Markdowndocs
         "<pre><code>#{ERB::Util.html_escape(code)}</code></pre>"
       end
 
+      # Force commonmarker to pass raw HTML through when SVG is allowed, so the
+      # markup reaches the sanitizer (the security boundary) instead of being
+      # escaped. Returns a copy — does not mutate the configured options.
+      def markdown_render_options
+        options = Markdowndocs.config.markdown_options
+        return options unless Markdowndocs.config.allow_svg
+
+        options.merge(render: (options[:render] || {}).merge(unsafe: true))
+      end
+
+      BASE_SANITIZE_TAGS = %w[
+        h1 h2 h3 h4 h5 h6 p br hr blockquote
+        ul ol li dl dt dd
+        table thead tbody tfoot tr th td
+        a img
+        strong em b i u del
+        code pre span div
+        details summary
+      ].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 desc
+      ].freeze
+
+      SVG_SANITIZE_ATTRS = %w[
+        viewBox d points
+        x y x1 y1 x2 y2 cx cy r rx ry width height
+        fill stroke stroke-width stroke-linecap stroke-linejoin stroke-dasharray
+        transform opacity text-anchor dominant-baseline
+        font-size font-family font-weight
+        marker-start marker-end markerWidth markerHeight refX refY orient
+        id xmlns focusable tabindex
+      ].freeze
+
       def sanitize_html(html)
-        sanitizer = Rails::HTML5::SafeListSanitizer.new
+        allow_svg = Markdowndocs.config.allow_svg
 
-        sanitizer.sanitize(
+        Rails::HTML5::SafeListSanitizer.new.sanitize(
           html,
-          tags: %w[
-            h1 h2 h3 h4 h5 h6 p br hr blockquote
-            ul ol li dl dt dd
-            table thead tbody tfoot tr th td
-            a img
-            strong em b i u del
-            code pre span div
-          ],
-          attributes: %w[
-            href title
-            src alt
-            align
-            class lang
-          ]
+          tags: allow_svg ? BASE_SANITIZE_TAGS + SVG_SANITIZE_TAGS : BASE_SANITIZE_TAGS,
+          attributes: allow_svg ? BASE_SANITIZE_ATTRS + SVG_SANITIZE_ATTRS : BASE_SANITIZE_ATTRS
         )
       end
     end

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

@@ -41,7 +41,8 @@
           turbo_action: "replace"
         }
       ) do |f| %>
-        <%= f.hidden_field :mode, value: mode %>
+        <%= f.hidden_field :mode, value: mode, id: nil %>
+        <%= f.hidden_field :current_path, value: request.fullpath, id: nil %>
         <button
           type="submit"
           role="radio"

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

@@ -1,3 +1,5 @@
+<% content_for :title, "#{@doc.title} — Documentation" %>
+
 <div class="min-h-screen bg-gray-50 dark:bg-slate-900">
   <div class="max-w-7xl mx-auto px-4 py-12
         sm:px-6
@@ -66,7 +68,10 @@
           lg:grid-cols-12">
       <!-- Main content -->
       <main class="lg:col-span-8">
-        <article class="bg-white dark:bg-slate-800 rounded-lg shadow-sm p-8">
+        <article
+          tabindex="-1"
+          autofocus
+          class="bg-white dark:bg-slate-800 rounded-lg shadow-sm p-8">
           <div class="prose prose-indigo dark:prose-invert max-w-none">
             <%= raw @rendered_content %>
           </div>

data/config/routes.rb

@@ -3,6 +3,20 @@
 Markdowndocs::Engine.routes.draw do
   root "docs#index"
   get "search_index", to: "docs#search_index", as: :search_index
+
+  # Mode-scoped doc route: matches /<mode>/<slug> where <mode> is one of
+  # the configured modes. Must come BEFORE the unconstrained :slug route
+  # so the more specific match wins.
+  #
+  # The constraint reads live config so dev-reload edits to config.modes
+  # take effect without a full server restart. Proc constraints apply only
+  # to request recognition; URL generation remains permissive.
+  mode_constraint = lambda do |request|
+    mode = request.path_parameters[:mode]
+    Array(Markdowndocs.config.modes).include?(mode)
+  end
+  get ":mode/:slug", to: "docs#show", as: :scoped_doc, constraints: mode_constraint
+
   get ":slug", to: "docs#show", as: :doc
   resource :preference, only: [:update]
 end

data/lib/generators/markdowndocs/install/templates/initializer.rb

@@ -5,14 +5,27 @@ Markdowndocs.configure do |config|
   # config.docs_path = Rails.root.join("app", "docs")
 
   # Category → slug mapping
-  # Maps category names to arrays of markdown file slugs (filenames without .md)
+  # Maps category names to arrays of markdown file slugs (filenames without .md).
+  # Bare slugs ("welcome") match files at app/docs/. Path-prefixed slugs
+  # ("technical/architecture") match files in mode subdirectories — see modes
+  # below.
   config.categories = {
     # "Getting Started" => %w[introduction quickstart],
     # "Guides" => %w[authentication deployment],
-    # "Reference" => %w[api-reference configuration]
+    # "Reference" => %w[api-reference technical/architecture]
   }
 
   # Available documentation modes (default: %w[guide technical])
+  #
+  # Each entry in `modes` also doubles as a path-based audience scope: files
+  # under `app/docs/<mode>/` are visible ONLY in that mode and served at
+  # `/docs/<mode>/<slug>`. Files at the docs root are shared across all modes.
+  #
+  #   app/docs/
+  #   ├── welcome.md              → shared, visible in every mode
+  #   └── technical/
+  #       └── architecture.md     → technical mode only
+  #
   # config.modes = %w[guide technical]
 
   # Default mode (default: "guide")
@@ -28,6 +41,11 @@ Markdowndocs.configure do |config|
   # Adds a search bar that filters docs by title, description, and content
   # config.search_enabled = true
 
+  # Allow a curated, safe subset of inline SVG for hand-authored diagrams
+  # (default: false). Scripts, event handlers, and javascript: URIs are
+  # always stripped by the sanitizer regardless of this setting.
+  # config.allow_svg = true
+
   # Optional: Resolve current user's mode preference from database
   # Return nil to fall back to cookie/default
   # config.user_mode_resolver = ->(controller) {

data/lib/markdowndocs/configuration.rb

@@ -2,15 +2,24 @@
 
 module Markdowndocs
   class Configuration
-    attr_accessor :docs_path, :categories, :modes, :default_mode,
+    # Route segments owned by the engine itself. A mode name matching any
+    # of these would collide with built-in routes / controller actions.
+    RESERVED_MODE_NAMES = %w[search_index preference preferences].freeze
+
+    attr_accessor :docs_path, :categories, :default_mode,
       :markdown_options, :rouge_theme, :cache_expiry,
       :user_mode_resolver, :user_mode_saver, :search_enabled,
-      :layout
+      :layout, :allow_svg
+    attr_reader :modes, :non_mode_subdirs_warned, :audience_deprecation_emitted
+
+    def modes=(value)
+      @modes = normalize_modes(value)
+    end
 
     def initialize
       @docs_path = nil # Resolved lazily so Rails.root is available
       @categories = {}
-      @modes = %w[guide technical]
+      self.modes = %w[guide technical]
       @default_mode = "guide"
       @markdown_options = default_markdown_options
       @rouge_theme = "github"
@@ -19,6 +28,13 @@ module Markdowndocs
       @user_mode_saver = nil
       @search_enabled = false
       @layout = "markdowndocs/application"
+      # Opt-in: allow a curated, safe inline-SVG subset in rendered docs.
+      # When true, the renderer passes raw HTML through commonmarker (unsafe)
+      # and the sanitizer (the security boundary) whitelists structural SVG
+      # tags/attributes while still stripping scripts/handlers. Default off.
+      @allow_svg = false
+      @non_mode_subdirs_warned = Set.new
+      @audience_deprecation_emitted = Set.new
     end
 
     # Lazily resolve docs_path so Rails.root is available
@@ -28,6 +44,38 @@ module Markdowndocs
 
     private
 
+    def normalize_modes(value)
+      list = Array(value).map do |entry|
+        unless entry.is_a?(String)
+          raise ArgumentError,
+            "config.modes entries must be strings; got #{entry.inspect}"
+        end
+
+        name = entry.strip
+
+        if name.empty?
+          raise ArgumentError, "config.modes contains an invalid empty entry"
+        end
+
+        if name.match?(%r{[/?#&\s]})
+          raise ArgumentError,
+            "config.modes entry #{entry.inspect} is invalid — names cannot contain " \
+            "path separators, URL-significant characters, or whitespace"
+        end
+
+        if RESERVED_MODE_NAMES.include?(name)
+          raise ArgumentError,
+            "config.modes entry #{name.inspect} is reserved by the engine " \
+            "(conflicts with built-in route or controller). " \
+            "Reserved names: #{RESERVED_MODE_NAMES.join(", ")}"
+        end
+
+        name
+      end
+
+      list.uniq
+    end
+
     def default_markdown_options
       {
         parse: {

data/lib/markdowndocs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markdowndocs
-  VERSION = "0.6.1"
+  VERSION = "0.9.0"
 end

data/lib/markdowndocs.rb

@@ -21,5 +21,12 @@ module Markdowndocs
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    # Deprecation channel for the gem. Hosts can attach custom behaviors
+    # (e.g., raise in test, silence in production) via:
+    #   Markdowndocs.deprecator.behavior = :log
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("1.0.0", "Markdowndocs")
+    end
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdowndocs
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Dave Chmura
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -103,7 +104,6 @@ files:
 - lib/markdowndocs/configuration.rb
 - lib/markdowndocs/engine.rb
 - lib/markdowndocs/version.rb
-- log/test.log
 - sig/markdowndocs.rbs
 homepage: https://github.com/dschmura/markdowndocs
 licenses:
@@ -112,6 +112,7 @@ metadata:
   homepage_uri: https://github.com/dschmura/markdowndocs
   source_code_uri: https://github.com/dschmura/markdowndocs
   changelog_uri: https://github.com/dschmura/markdowndocs/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -126,7 +127,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: A drop-in markdown documentation site for Rails apps
 test_files: []

data/log/test.log

@@ -1,4 +0,0 @@
-Started GET "/docs/..%2F..%2Fetc%2Fpasswd" for 127.0.0.1 at 2026-02-19 21:15:40 -0500
-  
-ActionController::RoutingError (No route matches [GET] "/docs/..%2F..%2Fetc%2Fpasswd"):
-