markdowndocs 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75c53c564b04a6a6a957dc2b038121c542e924d97908f5001c100cbca060d3a6
-  data.tar.gz: f791c421dd96c2c81b9bd49019216b72bb796aef43965157e3a608309d25e47d
+  metadata.gz: 764b5150885d6a306eae6d49fbabd8dedee96dffa9bc55a6f290da57e3b53123
+  data.tar.gz: 2a75805e06c5caa6fcdbf8e4860836bcf886fc5453b4d394761f8f45ae8ba114
 SHA512:
-  metadata.gz: 4af4914a66d3a2bcbdedcfb6e375573897dc1127199c6eabf6b0784f817741fcdb90ba732c4c8f1601bc56eb913781dc89dd59507c18c09ffea490ed211695e3
-  data.tar.gz: 3d733bca1efcdbb749a35491506f0d0f13ac4e7ed1f2f04ea6ee698cd94854cec7791e374ad02211a020a2d1012334639c49c5d87e1adb8b2b531a4f57d39be1
+  metadata.gz: 8502ba23be6b2ccafa8abc6f0388fddfaf1eae79da276b2ec676087195f04ddc000c576b636c5f81473c10fe30f2786faa9fa7b901419a3f8689226d6440a86e
+  data.tar.gz: 0d71e8284d7a5ed9efcdd8841e0a7e760bb26906e4ac61fb27a1ec32e259357c920e6b86ff66bc16e7d3fdda632c2ed5c12b216ff2b71c1f025f3f1ab73aab99

data/CHANGELOG.md

@@ -5,6 +5,17 @@ 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

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/controllers/markdowndocs/preferences_controller.rb

@@ -43,22 +43,36 @@ 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) && current_path != scoped_url
         scoped_url
-      elsif root_file.exist? && current_path != root_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>.

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/config/routes.rb

@@ -7,12 +7,15 @@ Markdowndocs::Engine.routes.draw do
   # 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.
-  mode_constraint = if Markdowndocs.config.modes.any?
-    Regexp.new("(?:#{Markdowndocs.config.modes.map { |m| Regexp.escape(m) }.join("|")})")
-  else
-    /impossible/
+  #
+  # 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: mode_constraint}
+  get ":mode/:slug", to: "docs#show", as: :scoped_doc, constraints: mode_constraint
 
   get ":slug", to: "docs#show", as: :doc
   resource :preference, only: [:update]

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,16 +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, :allow_svg
-    attr_reader :non_mode_subdirs_warned, :audience_deprecation_emitted
+    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"
@@ -36,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.8.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdowndocs
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  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
@@ -97,15 +98,12 @@ files:
 - config/importmap.rb
 - config/locales/en.yml
 - config/routes.rb
-- docs/superpowers/plans/2026-05-15-path-based-audience-routing.md
-- docs/superpowers/specs/2026-05-15-path-based-audience-routing-design.md
 - lib/generators/markdowndocs/install/install_generator.rb
 - lib/generators/markdowndocs/install/templates/initializer.rb
 - lib/markdowndocs.rb
 - 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:
@@ -114,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
@@ -128,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: []