markdowndocs 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dea93a9abe255c4c491211a174eea97d253c4a817d7bd5811b21dab335e3052
-  data.tar.gz: 2ef4fd88793a8600f815a7bfe4826c3fb312ab4dda38771b3cc5b8163a33929c
+  metadata.gz: 57e0fd3a2811b71d43a7e32029abd3a252af462158017fe7dff81abe94b827eb
+  data.tar.gz: bc74b02043fb27fa165d89cbbad04f8c89209fd45ef584ac6e1d017ffd89548b
 SHA512:
-  metadata.gz: 65669141ca36724f5e9d70ac6ed57d252ee93c33087d0d602391131049c2e4d258733f398d0c9dfcadeaa5f4ffd2b8a27ed55e4e083472848b67c3a9b16f3c4b
-  data.tar.gz: 135b31877bd880d9716f9dd897a25c57c162dfe434be98914e24df9da12ee5b4dc5dce20c061c2e1dc87db0d38eafbbb57912d60a4b845ee0863db0995951e35
+  metadata.gz: ce7f0b7b5ad9e21ff9b58d7bfe5a55319b127b68b9f614d33c69c2d825f3cb33bf8e58be7915ab619bcdb54b3830b7d699ed2ea1efa995204b7759f1967a45bc
+  data.tar.gz: 2fbb656ed33f668b517f2d8a105fd3c1be00a2b0a3f6d212f7fc80b603118121e5eea04e569ea7d75d0146a82537c299a65cebfc425e9b36dd49a5205aa1e60f

data/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.6.0] - 2026-05-13
+
+### Added
+
+- `audience:` frontmatter key on individual docs. Accepts a single string
+  or an array of mode names (e.g. `audience: technical`, or
+  `audience: [guide, technical]`). When the current mode does not appear
+  in a doc's audience, the doc is hidden from the index and unreachable
+  via slug (returns 404). Docs WITHOUT an `audience:` key remain visible
+  in every mode — fully backward compatible with pre-0.6 docs.
+- `Documentation#audience` returns the resolved audience as `Array<String>`.
+- `Documentation#visible_to?(mode)` predicate. `nil` mode means no filter.
+- `Documentation.find_by_slug(slug, mode: nil)` and
+  `Documentation.grouped_by_category(mode: nil)` both accept an optional
+  `mode:` kwarg. Default behavior (no kwarg) is unchanged — backward
+  compatible signature.
+
+### Changed
+
+- `Documentation.grouped_by_category` now drops empty categories when a
+  `mode:` filter is applied — categories whose docs are all hidden by the
+  current audience no longer render as empty headers.
+- `Markdowndocs::DocsController#index` and `#show` pass the resolved
+  `@docs_mode` through to `Documentation` so the index reflects the
+  user's mode pick. URL guessing / shared links to wrong-audience docs
+  now return 404.
+
+### Migration notes
+
+- No action required if you don't use modes. Existing docs continue to
+  appear in both `guide` and `technical` modes.
+- To restrict a doc to a specific audience, add `audience: technical`
+  (or `audience: guide`) to its frontmatter.
+- To make a doc explicitly multi-audience, use `audience: [guide, technical]`.
+
 ## [0.5.0] - 2026-05-05
 
 ### Added

data/README.md

@@ -108,6 +108,9 @@ 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
@@ -121,6 +124,24 @@ 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)
+
+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:
+
+```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
+```
+
+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.
+
 ### Mode Blocks
 
 Use HTML comments to show content only in specific modes:

data/app/controllers/markdowndocs/docs_controller.rb

@@ -9,7 +9,10 @@ module Markdowndocs
     SAFE_SLUG_PATTERN = /\A[a-zA-Z0-9_-]+\z/
 
     def index
-      @docs_by_category = Documentation.grouped_by_category
+      # Pass the resolved mode so docs whose `audience:` frontmatter
+      # excludes it are hidden from the index. Categories with no
+      # surviving docs are dropped (see Documentation.grouped_by_category).
+      @docs_by_category = Documentation.grouped_by_category(mode: @docs_mode)
       @search_enabled = Markdowndocs.config.search_enabled
     end
 
@@ -38,7 +41,12 @@ module Markdowndocs
     end
 
     def show
-      @doc = Documentation.find_by_slug(params[:slug])
+      # 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)
 
       if @doc.nil?
         render_not_found

data/app/models/markdowndocs/documentation.rb

@@ -23,14 +23,21 @@ module Markdowndocs
       end.sort_by(&:slug)
     end
 
-    def self.find_by_slug(slug)
+    # 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.
+    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?
 
-      new(file_path)
+      doc = new(file_path)
+      return nil unless doc.visible_to?(mode)
+
+      doc
     rescue => e
       Rails.logger.error("Error finding documentation by slug '#{slug}': #{e.message}")
       nil
@@ -40,9 +47,13 @@ module Markdowndocs
       all.select { |doc| doc.category == category }
     end
 
-    def self.grouped_by_category
+    # 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).
+    def self.grouped_by_category(mode: nil)
       Markdowndocs.config.categories.each_with_object({}) do |(category, slugs), hash|
-        hash[category] = slugs.map { |slug| find_by_slug(slug) }.compact
+        docs = slugs.map { |slug| find_by_slug(slug, mode: mode) }.compact
+        hash[category] = docs unless docs.empty?
       end
     end
 
@@ -83,6 +94,32 @@ 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).
+    def audience
+      @audience ||= begin
+        parsed = parse_frontmatter
+        raw = parsed[:frontmatter]["audience"]
+        case raw
+        when Array  then raw.map(&:to_s)
+        when String then [ raw ]
+        when nil    then Markdowndocs.config.modes.dup
+        else             Markdowndocs.config.modes.dup
+        end
+      end
+    end
+
+    # Whether this doc should be surfaced to a viewer in the given mode.
+    # `nil` mode is treated as "no filter" — useful for callers that
+    # don't care about audience (search indexer, admin tools).
+    def visible_to?(mode)
+      return true if mode.nil?
+      audience.include?(mode.to_s)
+    end
+
     # Returns content stripped of frontmatter, markdown syntax, and HTML tags
     # for use in search indexing.
     def plain_text_content

data/lib/markdowndocs/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markdowndocs
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Dave Chmura