markdowndocs 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57e0fd3a2811b71d43a7e32029abd3a252af462158017fe7dff81abe94b827eb
-  data.tar.gz: bc74b02043fb27fa165d89cbbad04f8c89209fd45ef584ac6e1d017ffd89548b
+  metadata.gz: 75c53c564b04a6a6a957dc2b038121c542e924d97908f5001c100cbca060d3a6
+  data.tar.gz: f791c421dd96c2c81b9bd49019216b72bb796aef43965157e3a608309d25e47d
 SHA512:
-  metadata.gz: ce7f0b7b5ad9e21ff9b58d7bfe5a55319b127b68b9f614d33c69c2d825f3cb33bf8e58be7915ab619bcdb54b3830b7d699ed2ea1efa995204b7759f1967a45bc
-  data.tar.gz: 2fbb656ed33f668b517f2d8a105fd3c1be00a2b0a3f6d212f7fc80b603118121e5eea04e569ea7d75d0146a82537c299a65cebfc425e9b36dd49a5205aa1e60f
+  metadata.gz: 4af4914a66d3a2bcbdedcfb6e375573897dc1127199c6eabf6b0784f817741fcdb90ba732c4c8f1601bc56eb913781dc89dd59507c18c09ffea490ed211695e3
+  data.tar.gz: 3d733bca1efcdbb749a35491506f0d0f13ac4e7ed1f2f04ea6ee698cd94854cec7791e374ad02211a020a2d1012334639c49c5d87e1adb8b2b531a4f57d39be1

data/CHANGELOG.md

@@ -5,6 +5,118 @@ 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.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
+
+- **Duplicate `id="docs-mode-switcher"` in the DOM** (issue #20). The
+  show layout renders `_navigation` (and therefore the mode switcher)
+  twice — once for the mobile sidebar, once for the desktop sidebar.
+  The hardcoded id on `_mode_switcher.html.erb` produced two elements
+  with the same id on every doc show page, a WCAG 4.1.1 violation.
+
+  Dropped the `id=` from the partial entirely. Stimulus already scopes
+  the controller via `data-controller="docs-mode"`, which can appear
+  N times in a document without colliding.
+
+  Host apps / tests / custom CSS selecting via `#docs-mode-switcher`
+  should switch to `[data-controller="docs-mode"]`. Note: any host app
+  relying on that id was already in a broken state (duplicate ids in
+  the DOM); this fix surfaces the issue rather than creating it.
+
+### Migration notes
+
+- If you have a CSS rule like `#docs-mode-switcher { ... }`, change it
+  to `[data-controller="docs-mode"] { ... }`.
+- If you have a Capybara test using `within "#docs-mode-switcher"`,
+  change it to `within first("[data-controller='docs-mode']")` (or
+  similar — the partial may render twice depending on your layout).
+
 ## [0.6.0] - 2026-05-13
 
 ### Added
@@ -167,6 +279,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                                                    |
@@ -124,23 +134,43 @@ Your content here...
 
 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
+```
+
+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.
 
-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:
+### 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.
 
 ```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
 
@@ -303,6 +333,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,74 @@ 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?
+
+      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
+        scoped_url
+      elsif root_file.exist? && current_path != root_url
+        root_url
+      else
+        current_path
+      end
+    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