docs-kit 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04c64683910c10c37f660008f8891ca9f87296a0aea1ddc67f9d9a199975cccd
-  data.tar.gz: d357822c1df8899b50008f28366992bde0b9d6f622ec90975b5926f11d2de2d7
+  metadata.gz: feed239eb09deeafd1a9dc6e92e91d192c14f927fa562105139f4b16473d1a60
+  data.tar.gz: 6149bf7b9509fb611ce86e9c183a38c027ce77addee69669be41a0ce85fb292d
 SHA512:
-  metadata.gz: a2b905a1b80c5e156ea7e652ba45cb4d2ec54c91ad040754112cdd481644b7698fd5356459faf06f46ac140c0c6562b8989039b69585b3f257a3b5629cfe0d49
-  data.tar.gz: 9837ae7885fb3c6ad358b585853aa7d0dee63b9807c574f15e8543f70ae5de6ecea4f5a2755391588a111fa5d05fcf2456a76b9040a648b86bcf3cf767700171
+  metadata.gz: 5af123f6815e81ccad67dcb7737836c0a2727fb60e963bfc16d6ff0a6540325ca1a67fa2aaaea2ff824ba3b36f2210d8fb4aaab43f097195ec7f020cbfc8c54e
+  data.tar.gz: 32e24110ca11cfba1c795d60ea93d6ecb2f1e42af912274ebc816718cd235d93e217bb1ac2a6082b08039eaefe162c6b8287f4ed328c685ab3c669c840e2e359

data/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## [Unreleased]
 
+## [1.3.0] — 2026-10-13
+
+### Fixed
+
+- **Markdown links drop a script-bearing href.** `[text](javascript:…)`,
+  `data:`, `vbscript:` and any other scheme outside http(s), `mailto:` and
+  `tel:` now render the link text with no `<a>` (Phlex already refused
+  `javascript:`; `data:` and the rest slipped through). Scheme-less hrefs are
+  unchanged. The same guard `DocsUI::Markdown` images have.
+
+### Added
+
+- **A per-request `brand` and `title_suffix`.** Both accept a zero-arity
+  callable (`c.brand = -> { Current.tenant_name }`), evaluated on every render:
+  the topbar, sidebar header, `<title>`, `og:site_name`, llms.txt and the MCP
+  server name show that request's value. A callable brand needs an explicit
+  `c.nav_storage_key`; `DocsKit.configure` raises without one. New readers
+  `Configuration#brand_text` / `#title_suffix_text`; a String brand renders
+  exactly as before. (#92)
+- **Markdown images render.** `![alt](path "title")` in an `md` island now
+  renders a lazy-loaded `<img>` (it rendered nothing before). In a Rails view
+  a relative path resolves through the site's asset pipeline (`image_path`;
+  off a request it is kept as written); an absolute,
+  protocol-relative or root-relative URL is kept as written; the alt is the
+  description's plain text. A `javascript:`, `data:` or other non-http(s)
+  scheme renders no image. The page's `.md` twin exports it back to
+  `![alt](src)`. (#94)
+- **A dedicated docs import map.** `c.importmap_entry_point` (default
+  `"application"`) and `c.importmap` (an `Importmap::Map` or a callable
+  returning one, resolved per render) choose what the Shell's
+  `javascript_importmap_tags` loads, and `config.docs_kit.auto_pin = false` (in
+  `config/application.rb`) keeps the gem's `docs-nav` pin out of the host's
+  shared map. Unset, the head is unchanged. (#93)
+- **`DocsUI::Page` title, description and eyebrow per instance.** The page now
+  reads `#title`, `#description` and `#eyebrow`, which default to the class
+  macros, so one page class can render many records (`def title = @widget.name`)
+  without an anonymous subclass per render. The `eyebrow`, `description` and
+  `on_page` macros inherit from a parent page when unset. Pages using only the
+  class macros render byte-identically. (#95)
+
+## [1.2.1] — 2026-09-30 (with 1.2.0, same day)
+
 ### Upgrading from 1.1
 
 ```bash

data/README.md

@@ -193,6 +193,20 @@ DocsKit.configure do |c|
 end
 ```
 
+**One app, several hosts?** `brand` and `title_suffix` also take a zero-arity
+callable, evaluated on every render — the topbar, the sidebar header, `<title>`,
+`og:site_name`, llms.txt and the MCP server name all show that request's value.
+A callable brand can't name the localStorage namespace (it must stay stable per
+browser), so set `nav_storage_key` too; `DocsKit.configure` raises without it.
+
+```ruby
+DocsKit.configure do |c|
+  c.brand           = -> { Current.tenant_name }   # Current < ActiveSupport::CurrentAttributes
+  c.title_suffix    = -> { "#{Current.tenant_name} docs" } # optional; unset follows the brand
+  c.nav_storage_key = "docs"
+end
+```
+
 The nav is **derived from the registry**, so you never hand-write it. Each
 registry maps a heading to its authored pages (`Doc.nav_items`); a page that
 isn't written yet is skipped, so there are no dead links. Register a page with
@@ -431,6 +445,37 @@ end
 `DocsUI::Page` includes the kit, so inside `#content` you call the components
 directly — `DocsUI::Section(...)`, `DocsUI::Code(...)` — no `render … .new`.
 
+### One page class, many records
+
+`title`, `eyebrow` and `description` are class macros by default, but the page
+reads them through **instance** methods — override those when one page class
+renders many records (one reference page per item):
+
+```ruby
+class Views::Docs::Widget < DocsUI::Page
+  eyebrow "Widgets"
+
+  def initialize(widget:) = @widget = widget
+  def title = @widget.name                # masthead <h1> and <title>
+  def description = @widget.summary       # meta/OG description (default: class macro, then #lead)
+  def content = md(@widget.notes)
+end
+
+# controller
+def show = render_page(Views::Docs::Widget.new(widget: Widget.find(params[:id])))
+```
+
+`eyebrow`, `description` and `on_page` inherit: a subclass that leaves one unset
+uses its parent page's. `title` does not — each page names itself.
+
+Such a page usually lives on its own route, outside the registry. If that route
+has no `(.:format)` segment, the masthead's **Markdown** action (which links
+`request.path + ".md"`) would 404 — hide it for that page:
+
+```ruby
+def markdown_action? = false
+```
+
 ### The authoring convention
 
 One rule covers the whole kit: **the primary argument is positional; modifiers
@@ -1051,6 +1096,42 @@ server round-trip:
   of three placements, auto-hiding on short pages. No server-side knowledge of
   the headings, no per-page wiring.
 
+### A dedicated docs import map
+
+By default the Shell loads the host's `application` entry point from
+`Rails.application.importmap`, and the engine adds the `docs-nav` pin to that
+map. A host with several import maps can give its docs their own entry point
+and map, and keep the docs controller out of every other page's preloads:
+
+```ruby
+# config/application.rb — skip the engine's auto-pin into the shared map
+config.docs_kit.auto_pin = false
+
+# config/initializers/docs_kit.rb — build the second map (importmap-rails has no
+# registry for extra maps; the host owns it) and point the docs chrome at it
+DOCS_IMPORTMAP = Importmap::Map.new.draw(Rails.root.join("config/importmaps/docs.rb"))
+
+DocsKit.configure do |c|
+  c.importmap_entry_point = "docs"          # default "application"
+  c.importmap = -> { DOCS_IMPORTMAP }       # default nil → Rails.application.importmap
+end
+```
+
+```ruby
+# config/importmaps/docs.rb — drawn into the docs Importmap::Map above
+pin "docs"
+pin "@hotwired/turbo-rails", to: "turbo.min.js"
+pin "@hotwired/stimulus", to: "stimulus.min.js"
+pin "@hotwired/stimulus-loading", to: "stimulus-loading.js"
+pin_all_from DocsKit::Engine.root.join("app/javascript/docs_kit/controllers"),
+             under: "docs_kit/controllers", to: "docs_kit/controllers"
+```
+
+`c.importmap` takes an `Importmap::Map` or a callable returning one; a callable
+is resolved on every render, so a map rebuilt on code reload is picked up. The
+`docs` entry point registers the controllers with
+`eagerLoadControllersFrom("docs_kit/controllers", application)`.
+
 ### On this page (auto-TOC)
 
 `DocsUI::Page` renders it automatically. The placement is a strategy — set the

data/app/components/docs_ui/landing.rb

@@ -33,7 +33,7 @@ module DocsUI
     include Phlex::Rails::Helpers::Request
 
     def view_template
-      render DocsUI::Shell.new(title: landing.eyebrow || config.brand) do
+      render DocsUI::Shell.new(title: landing.eyebrow || config.brand_text) do
         div(class: "mx-auto max-w-5xl") do
           hero
           feature_grid
@@ -78,7 +78,7 @@ module DocsUI
     # (the one bit of markdown we honor, so a site can accent a word without HTML).
     def heading
       h1(class: "text-4xl font-bold tracking-tight md:text-5xl") do
-        (landing.title || config.brand).to_s.split(/\*\*(.+?)\*\*/).each_with_index do |part, index|
+        (landing.title || config.brand_text).to_s.split(/\*\*(.+?)\*\*/).each_with_index do |part, index|
           next if part.empty?
 
           index.odd? ? span(class: "text-primary") { part } : plain(part)

data/app/components/docs_ui/markdown.rb

@@ -34,6 +34,9 @@ module DocsUI
     TABLE_WRAPPER = "not-prose my-4 overflow-x-auto rounded-box border border-base-300"
     TABLE_CLASSES = "table table-sm table-zebra"
 
+    # ![alt](src) → <img>, asset-pipeline resolved (see MarkdownImages).
+    include MarkdownImages
+
     # Render source as INLINE markdown: no Prose wrapper div, and a single
     # top-level paragraph is unwrapped so its inline children (strong/em/code/
     # link) sit directly in the surrounding element. Used for a [:md, "…"] table
@@ -88,9 +91,7 @@ module DocsUI
 
     def node_document(node) = visit_children(node)
 
-    def node_paragraph(node)
-      p { visit_children(node) }
-    end
+    def node_paragraph(node) = p { visit_children(node) }
 
     # Demote so Markdown headings never collide with the page masthead/section
     # headings: h1→h3, h2→h4, anything deeper caps at h4.
@@ -127,8 +128,11 @@ module DocsUI
       render DocsUI::Code.new(node.string_content, lexer:)
     end
 
+    # A link keeps its href only for an allowed scheme (MarkdownImages::
+    # LINK_SCHEMES) or none at all; otherwise the text renders bare.
     def node_link(node)
-      a(href: node.url) { visit_children(node) }
+      href = link_href(node.url)
+      href ? a(href:) { visit_children(node) } : visit_children(node)
     end
 
     def node_list(node)

data/app/components/docs_ui/markdown_images.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # DocsUI::Markdown's image handler: `![alt](src "title")` → a lazy-loaded
+  # <img>. A relative src resolves through the site's asset pipeline
+  # (image_path → the digested /assets URL, Propshaft or Sprockets); an absolute,
+  # protocol-relative or root-relative URL is kept as written. Off a request (an
+  # isolated render) the src is used verbatim — the DocsUI::Logo posture.
+  module MarkdownImages
+    include Phlex::Rails::Helpers::ImagePath
+
+    # A Markdown image sits in the prose like the kit's other bordered boxes.
+    IMAGE_CLASSES = "my-4 rounded-box border border-base-300"
+
+    # An image src kept verbatim: absolute, protocol-relative or root-relative.
+    ABSOLUTE_SRC = %r{\A(?:https?:)?/}i
+
+    # Any URL scheme. An image src may only carry http(s); a link href one of
+    # LINK_SCHEMES. Scheme-less URLs (relative, root-relative, protocol-relative,
+    # #anchor) always pass; javascript:, data:, vbscript: and the rest never do.
+    URL_SCHEME = /\A[a-z][a-z0-9+.-]*:/i
+    LINK_SCHEMES = %w[http https mailto tel].freeze
+
+    # The descendants whose string_content makes up the alt text; a soft or hard
+    # line break between them becomes a space so words don't run together.
+    ALT_TEXT_NODES = %i[text code].freeze
+    ALT_BREAK_NODES = %i[softbreak linebreak].freeze
+
+    private
+
+    # An unsafe scheme renders nothing — the alt text is dropped with it rather
+    # than left behind as stray prose.
+    def node_image(node)
+      src = image_src(node.url)
+      return unless src
+
+      title = node.title.to_s
+      img(src:, alt: alt_text(node), title: (title unless title.empty?),
+          loading: "lazy", class: IMAGE_CLASSES)
+    end
+
+    # Browsers strip ASCII whitespace/control characters before reading a
+    # scheme ("java\tscript:"), so the check does too.
+    def image_src(url)
+      bare = bare_url(url)
+      return url if bare.match?(ABSOLUTE_SRC)
+      return if bare.match?(URL_SCHEME)
+
+      view_context ? image_path(url) : url
+    end
+
+    # A link's href as written, or nil when it carries a scheme outside
+    # LINK_SCHEMES (the same whitespace-stripped scheme read as image_src).
+    def link_href(url)
+      scheme = bare_url(url)[URL_SCHEME]
+      return url if scheme.nil? || LINK_SCHEMES.include?(scheme.chomp(":").downcase)
+
+      nil
+    end
+
+    def bare_url(url) = url.to_s.gsub(/[\x00-\x20]/, "")
+
+    # Commonmarker 2 has no plain-text export, so the alt is the image's text
+    # (and inline code) descendants joined — emphasis markup is dropped.
+    def alt_text(node)
+      node.walk.filter_map do |n|
+        if ALT_TEXT_NODES.include?(n.type) then n.string_content
+        elsif ALT_BREAK_NODES.include?(n.type) then " "
+        end
+      end.join
+    end
+  end
+end

data/app/components/docs_ui/meta_tags.rb

@@ -52,7 +52,7 @@ module DocsUI
     # The full title used for og:title, identical to what Shell puts in <title>:
     # "Page · Suffix", or just the suffix on a title-less page (the home page).
     def full_title
-      [@title, config.title_suffix].compact.join(" · ")
+      [@title, config.title_suffix_text].compact.join(" · ")
     end
 
     def description_meta
@@ -67,7 +67,7 @@ module DocsUI
     def open_graph
       meta(property: "og:title", content: full_title)
       meta(property: "og:type", content: seo.og_type)
-      meta(property: "og:site_name", content: config.brand)
+      meta(property: "og:site_name", content: config.brand_text)
       open_graph_optional
     end
 

data/app/components/docs_ui/page.rb

@@ -14,6 +14,16 @@ module DocsUI
   #       render DocsUI::Section.new("Add the gem") { … }
   #     end
   #   end
+  #
+  # A page class that renders many records overrides the INSTANCE readers
+  # (#title, #description, #eyebrow) instead — they default to the class macros:
+  #
+  #   class Views::Docs::Widget < DocsUI::Page
+  #     eyebrow "Widgets"
+  #     def initialize(widget:) = @widget = widget
+  #     def title = @widget.name
+  #     def content = md(@widget.notes)
+  #   end
   class Page < Phlex::HTML
     include Phlex::Rails::Helpers::Routes
     # #request drives the "Markdown" masthead action's href (request.path + .md).
@@ -31,35 +41,42 @@ module DocsUI
         @title
       end
 
+      # Inherited: a subclass that sets no eyebrow shows its parent page's.
       def eyebrow(value = nil)
         @eyebrow = value if value
-        @eyebrow
+        @eyebrow || (superclass.eyebrow if parent_page?)
       end
 
       # The per-page SEO/social description → DocsUI::MetaTags (via Shell). Set it
       # for a hand-tuned description; when unset, Page derives one from #lead, so
       # an existing page gets a sensible description for free. nil (no
       # description, no lead) falls back to config.seo.description in MetaTags.
+      # Inherited from a parent page when unset.
       def description(value = nil)
         @description = value if value
-        @description
+        @description || (superclass.description if parent_page?)
       end
 
       # The "On this page" auto-TOC placement for this page. Defaults to the
       # configured DocsKit.configuration.on_page_default; set false to opt out,
-      # or :panel/:toggle/:sidebar to override per page.
+      # or :panel/:toggle/:sidebar to override per page. Inherited from a parent
+      # page when unset.
       def on_page(value = :__unset__)
         @on_page = value unless value == :__unset__
-        defined?(@on_page) ? @on_page : DocsKit.configuration.on_page_default
+        return @on_page if defined?(@on_page)
+
+        parent_page? ? superclass.on_page : DocsKit.configuration.on_page_default
       end
+
+      private
+
+      # Whether the superclass is a page too (true below DocsUI::Page itself), so
+      # an unset macro falls back to it.
+      def parent_page? = superclass <= DocsUI::Page
     end
 
     def view_template
-      render DocsUI::Shell.new(
-        title: self.class.title,
-        description: self.class.description || lead,
-        on_page: self.class.on_page
-      ) do
+      render DocsUI::Shell.new(title:, description:, on_page: self.class.on_page) do
         # data-md-skip drops this nav from the Markdown export — it's chrome, not
         # page content (DocsKit::MarkdownExport strips [data-md-skip]). The
         # "Markdown" action sits opposite "← Home"; it's chrome too, so it lives
@@ -69,7 +86,7 @@ module DocsUI
           render DocsUI::MarkdownAction.new(request.path) if markdown_action?
         end
 
-        render DocsUI::Header.new(self.class.title, eyebrow: self.class.eyebrow) do
+        render DocsUI::Header.new(title, eyebrow:) do
           plain lead if lead
         end
 
@@ -78,9 +95,19 @@ module DocsUI
     end
 
     # Whether to show the "Markdown" masthead action — the config knob
-    # (DocsKit.configuration.page_markdown_action, default true).
+    # (DocsKit.configuration.page_markdown_action, default true). The action links
+    # request.path + ".md"; override to false on a page whose route has no .md twin.
     def markdown_action? = DocsKit.configuration.page_markdown_action
 
+    # The page title (masthead <h1> and <title>), eyebrow and SEO description.
+    # Each defaults to its class macro; override per instance when one page class
+    # renders many records. #title shadows Phlex's <title> element method, on
+    # pages only — the document <title> is DocsUI::Shell's, never a page body's.
+    def title = self.class.title
+    def eyebrow = self.class.eyebrow
+    # Falls back to #lead, then (in DocsUI::MetaTags) to config.seo.description.
+    def description = self.class.description || lead
+
     # The lowercase authoring helpers md/prose/example come from DocsUI::PageHelpers
     # (included above) — the parens-free path that never hits the constant-reference
     # SyntaxError. The kit forms (DocsUI::Prose(), DocsUI::Example()) stay valid too.

data/app/components/docs_ui/shell.rb

@@ -72,9 +72,13 @@ module DocsUI
     # injected by the controller under the active nav link (no content slot).
     def content_toc? = %i[panel toggle].include?(@on_page)
 
+    # "Page · Suffix", or just the suffix on a title-less page. The suffix is
+    # resolved per render (a callable title_suffix/brand → this request's value).
+    def document_title = [@title, config.title_suffix_text].compact.join(" · ")
+
     def render_head
       head do
-        title { [@title, config.title_suffix].compact.join(" · ") }
+        title { document_title }
         meta(charset: "utf-8")
         meta(name: "viewport", content: "width=device-width,initial-scale=1")
         # SEO / social-share tags (description, Open Graph, Twitter Card,
@@ -90,10 +94,20 @@ module DocsUI
         meta(name: "turbo-refresh-scroll", content: "preserve")
         config.stylesheets.each { |sheet| stylesheet_link_tag(sheet, data: { turbo_track: "reload" }) }
         theme_restore_script
-        javascript_importmap_tags
+        importmap_tags
       end
     end
 
+    # The import map tags for config.importmap_entry_point, from config.importmap
+    # when one is set. With nothing configured this is the helper's own default
+    # call, so the head matches a Shell that predates the knobs.
+    def importmap_tags
+      map = config.resolved_importmap
+      return javascript_importmap_tags(config.importmap_entry_point) if map.nil?
+
+      javascript_importmap_tags(config.importmap_entry_point, importmap: map)
+    end
+
     # Restore the persisted theme BEFORE first paint so there's no flash of the
     # server default before the docs-nav controller runs. Reads the same
     # localStorage key the controller writes (docs-kit:<site>:theme). Runs on
@@ -183,9 +197,9 @@ module DocsUI
     # text brand stays the mark's accessible-name fallback.
     def brand_mark
       if (logo = config.brand_logo)
-        render DocsUI::Logo.new(logo, class: "h-6 w-auto", label: config.brand)
+        render DocsUI::Logo.new(logo, class: "h-6 w-auto", label: config.brand_text)
       else
-        plain config.brand
+        plain config.brand_text
       end
     end
 

data/app/components/docs_ui/sidebar.rb

@@ -59,9 +59,9 @@ module DocsUI
     # Slightly taller than the topbar's h-6: this is the masthead.
     def brand_mark
       if (logo = config.brand_logo)
-        render DocsUI::Logo.new(logo, class: "h-7 w-auto", label: config.brand)
+        render DocsUI::Logo.new(logo, class: "h-7 w-auto", label: config.brand_text)
       else
-        plain config.brand
+        plain config.brand_text
       end
     end
 

data/app/controllers/docs_kit/llms_controller.rb

@@ -71,9 +71,12 @@ module DocsKit
     # Revalidate on the rendered body itself (so any registry/config/page change
     # busts it) plus the gem version as the etag salt. In development, always
     # re-render; production sites deploy immutably so the version etag is stable.
+    # A callable brand (#92) makes the body per-request, so the response is then
+    # `private`: a shared cache must not hand one tenant's llms.txt to another.
     def stale_llms?(body)
-      expires_in LLMS_MAX_AGE, public: true
-      stale?(etag: [DocsKit::VERSION, body], public: true)
+      shared = !docs_config.brand_per_request?
+      expires_in LLMS_MAX_AGE, public: shared
+      stale?(etag: [DocsKit::VERSION, body], public: shared)
     end
 
     # A page's Markdown twin, rendered through this controller's view context so

data/lib/docs_kit/configuration.rb

@@ -78,6 +78,17 @@ module DocsKit
     # stylesheets (e.g. a separate rouge theme) lists them here.
     attr_accessor :stylesheets
 
+    # The import map entry point the Shell loads. Defaults to "application"
+    # (javascript_importmap_tags' own default). A host with a dedicated docs
+    # import map names its entry point here, e.g. "docs".
+    attr_accessor :importmap_entry_point
+
+    # The import map the Shell renders: nil (the default → the host's
+    # Rails.application.importmap), an Importmap::Map, or a zero-arity callable
+    # returning one, resolved per render so a map rebuilt on code reload is
+    # picked up. Read via #resolved_importmap.
+    attr_accessor :importmap
+
     # The Rouge theme class used by DocsUI::Code for inline syntax-highlight CSS.
     # This is the BASE (light) theme, emitted un-scoped so it applies to every
     # theme unless a dark override wins (see #code_theme_dark).
@@ -307,6 +318,8 @@ module DocsKit
       @nav_registries = {}
       @version_badge = nil
       @stylesheets = %w[application]
+      @importmap_entry_point = "application"
+      @importmap = nil
       @code_theme = "Rouge::Themes::Monokai"
       @code_theme_dark = nil
       @dark_themes = DEFAULT_DARK_THEMES
@@ -544,14 +557,54 @@ module DocsKit
 
     public
 
+    # The localStorage namespace. A callable brand can't be slugged: the key must
+    # be stable per browser, not per request, so a callable brand needs an
+    # explicit c.nav_storage_key (checked again by DocsKit.configure).
     def nav_storage_key
-      @nav_storage_key || @brand.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+      return @nav_storage_key if @nav_storage_key
+      if @brand.respond_to?(:call)
+        raise DocsKit::Error,
+              "c.brand is a callable, so set c.nav_storage_key to a stable key " \
+              "(the sidebar/theme localStorage namespace must not change per request)"
+      end
+
+      @brand.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
     end
 
+    # The raw configured suffix (or the raw brand when unset). The chrome reads
+    # #title_suffix_text, which resolves a callable.
     def title_suffix
       @title_suffix || @brand
     end
 
+    # The rendered brand. A String is returned as-is; a zero-arity callable is
+    # invoked on every read (never memoize it — the point is a per-request
+    # value, e.g. -> { Current.tenant_name }).
+    def brand_text
+      resolve_text(@brand).to_s
+    end
+
+    # True when the brand is a callable, i.e. anything that embeds the brand
+    # (the chrome, llms.txt) may differ per request and must not be stored in a
+    # shared cache.
+    def brand_per_request?
+      @brand.respond_to?(:call)
+    end
+
+    # The rendered <title>/og:title suffix: #title_suffix resolved like
+    # #brand_text, falling back to the resolved brand. nil only when both are nil,
+    # so the title join drops it instead of leaving a dangling separator.
+    def title_suffix_text
+      resolve_text(@title_suffix.nil? ? @brand : @title_suffix)
+    end
+
+    # Raises at configure time for a config the chrome can't render (today: a
+    # callable brand without a stable nav_storage_key). Called by DocsKit.configure.
+    def validate!
+      nav_storage_key
+      self
+    end
+
     # Whether the built-in MCP endpoint is active: the #mcp toggle is on AND the
     # optional `mcp` gem is loadable — the same "toggle AND capability" shape as
     # #search_enabled?. Read by DocsKit::LlmsText (to advertise /mcp in llms.txt)
@@ -609,6 +662,12 @@ module DocsKit
       @version_badge.to_s
     end
 
+    # The import map the Shell renders, or nil for the host's default map. A
+    # callable is invoked on every read (once per render).
+    def resolved_importmap
+      @importmap.respond_to?(:call) ? @importmap.call : @importmap
+    end
+
     # The default Rouge theme both #code_theme_class and #code_theme_dark_class
     # fall back to when a configured theme name can't be resolved — so a typo'd
     # theme name degrades gracefully instead of raising on every code block.
@@ -652,5 +711,12 @@ module DocsKit
     rescue NameError
       nil
     end
+
+    # A String-or-callable knob's value for this render: a callable is invoked
+    # and stringified, nil stays nil, anything else is stringified.
+    def resolve_text(value)
+      value = value.call if value.respond_to?(:call)
+      value&.to_s
+    end
   end
 end

data/lib/docs_kit/engine.rb

@@ -36,10 +36,17 @@ module DocsKit
       app.config.assets.paths << JAVASCRIPT_PATH.to_s if app.config.respond_to?(:assets)
     end
 
+    # Host-facing engine options. `config.docs_kit.auto_pin = false` (in
+    # config/application.rb) keeps the gem's pin out of the host's shared import
+    # map, for a host that pins `docs_kit/controllers` in a dedicated docs map.
+    config.docs_kit = ActiveSupport::OrderedOptions.new
+    config.docs_kit.auto_pin = true
+
     # Auto-pin the controller for importmap-rails consumers, so a host app gets
     # `docs_kit/controllers/docs_nav_controller` with no manual pin.
     initializer "docs_kit.importmap", before: "importmap" do |app|
       next unless app.config.respond_to?(:importmap)
+      next unless app.config.docs_kit.auto_pin
 
       importmap = app.config.importmap
       importmap.paths << root.join("config/importmap.rb") if importmap.respond_to?(:paths)

data/lib/docs_kit/llms_text.rb

@@ -33,7 +33,7 @@ module DocsKit
     # single tight list (no blank lines between bullets), per the llmstxt.org
     # convention.
     def index(config, base_url: nil)
-      blocks = ["# #{config.brand}"]
+      blocks = ["# #{config.brand_text}"]
       tagline = config.tagline
       blocks << "> #{tagline}" if tagline && !tagline.to_s.empty?
       blocks.concat(section_blocks(config, base_url))

data/lib/docs_kit/mcp_server.rb

@@ -28,7 +28,7 @@ module DocsKit
       return unless mcp_available?
 
       server = MCP::Server.new(
-        name: config.brand.to_s,
+        name: config.brand_text,
         version: DocsKit::VERSION,
         instructions: instructions_for(config, base_url),
         server_context: { config:, base_url:, view_context: }
@@ -54,7 +54,7 @@ module DocsKit
       lines = []
       tagline = config.tagline
       lines << tagline.to_s if tagline && !tagline.to_s.empty?
-      lines << "Read-only documentation tools for #{config.brand}. " \
+      lines << "Read-only documentation tools for #{config.brand_text}. " \
                "Use search_docs to find sections, get_page to read a page's Markdown, " \
                "and list_pages to enumerate the docs. Full index: #{llms}."
       lines.join(" ")

data/lib/docs_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DocsKit
-  VERSION = "1.2.1"
+  VERSION = "1.3.0"
 end

data/lib/docs_kit.rb

@@ -25,7 +25,7 @@ module DocsKit
 
     def configure
       yield(configuration)
-      configuration
+      configuration.validate!
     end
 
     def reset_configuration!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -179,6 +179,7 @@ files:
 - app/components/docs_ui/logo.rb
 - app/components/docs_ui/markdown.rb
 - app/components/docs_ui/markdown_action.rb
+- app/components/docs_ui/markdown_images.rb
 - app/components/docs_ui/meta_tags.rb
 - app/components/docs_ui/on_this_page.rb
 - app/components/docs_ui/open_api_operation.rb