markdowndocs 0.8.0 → 0.10.0

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.10.0"
 end

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.4.6"

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdowndocs
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Dave Chmura
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -74,6 +75,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".tool-versions"
 - CHANGELOG.md
 - README.md
 - Rakefile
@@ -90,6 +92,7 @@ files:
 - app/views/layouts/markdowndocs/application.html.erb
 - app/views/markdowndocs/docs/_breadcrumb.html.erb
 - app/views/markdowndocs/docs/_card.html.erb
+- app/views/markdowndocs/docs/_docs_toolbar.html.erb
 - app/views/markdowndocs/docs/_mode_switcher.html.erb
 - app/views/markdowndocs/docs/_navigation.html.erb
 - app/views/markdowndocs/docs/index.html.erb
@@ -97,15 +100,13 @@ 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
+- mise.toml
 - sig/markdowndocs.rbs
 homepage: https://github.com/dschmura/markdowndocs
 licenses:
@@ -114,6 +115,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 +130,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: []