docs-kit 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fee711dcf42e9b92cf749684ea9b94c07ef9d614cf21746881f2c7402f744ea
-  data.tar.gz: 76e246db5be838d3b31b8f08a98d033c57e3765d82900245723afc32fd4cad5f
+  metadata.gz: feed239eb09deeafd1a9dc6e92e91d192c14f927fa562105139f4b16473d1a60
+  data.tar.gz: 6149bf7b9509fb611ce86e9c183a38c027ce77addee69669be41a0ce85fb292d
 SHA512:
-  metadata.gz: 1a9cd702122f1e7af103b4279d7e3f4d45e8e662d5838931ac622383ce23609befd8557daddd2b3ac4afda772fc148cf0f5458546a8776b6bae3168408f59065
-  data.tar.gz: 05ce8bb90585331cdaefa92973c36b67d55b2b6164aae03f55d4679a35d8ce7c4128295e4919a3775123cecaa923355baf1622481741ca3a4312394d5b0dd0a2
+  metadata.gz: 5af123f6815e81ccad67dcb7737836c0a2727fb60e963bfc16d6ff0a6540325ca1a67fa2aaaea2ff824ba3b36f2210d8fb4aaab43f097195ec7f020cbfc8c54e
+  data.tar.gz: 32e24110ca11cfba1c795d60ea93d6ecb2f1e42af912274ebc816718cd235d93e217bb1ac2a6082b08039eaefe162c6b8287f4ed328c685ab3c669c840e2e359

data/CHANGELOG.md

@@ -2,6 +2,122 @@
 
 ## [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
+bundle update docs-kit
+bin/rails g docs_kit:install --sync   # applies the 1.2 migration, prints what it can't
+bun install && bun run build:css
+bundle exec rspec
+```
+
+- **Ruby 3.3 or newer is required.** docs-kit 1.2 won't install on 3.2. Move
+  `.ruby-version` and the Dockerfile's `ARG RUBY_VERSION` first (`--sync` warns
+  about either one if it's still below 3.3).
+- **`--sync` raises the toolchain it scaffolded.** In a Dockerfile that still
+  carries docs-kit's old `ARG BUN_VERSION=1.3.2`, it bumps that to 1.4.2. In
+  `package.json`, it raises docs-kit's old `tailwindcss` / `@tailwindcss/cli
+  ^4.1.18` and `daisyui ^5.6.0` floors to `^4.3.3` / `^5.7.47`. Values you
+  picked yourself are never rewritten: an older one is printed as a warning,
+  and a newer one is left alone. Review the result with `git diff`.
+- **Deploys pick up Node 24 actions and `ubuntu-26.04` automatically** when your
+  `deploy-docs.yml` calls `zoolutions/docs-kit/.github/workflows/deploy.yml@main`
+  (what `docs-kit new` scaffolds). `--sync` warns about a caller pinned to a tag
+  or SHA; move the pin forward.
+- **Untrack `app/assets/stylesheets/tailwind.sources.css`** if it's committed:
+  `git rm --cached app/assets/stylesheets/tailwind.sources.css`. The generator
+  now gitignores it; `--sync` reminds you when it's still tracked.
+
+### Removed
+
+- **Ruby 3.2 support.** `required_ruby_version` is now `>= 3.3` (3.2 reached
+  end of life in March 2026), and CI no longer tests it.
+
+### Changed
+
+- **daisyui 2.x is allowed.** The dependency is now `>= 1.2, < 3`. 1.2.0 was
+  tagged but never reached RubyGems (its release run failed a stale spec), so
+  1.2.1 is the first published 1.2 release.
+- **The reusable deploy workflow runs on Node 24 actions.** `deploy.yml` now
+  uses `actions/checkout@v7`, `docker/setup-buildx-action@v4`,
+  `docker/login-action@v4`, `docker/build-push-action@v7` and
+  `webfactory/ssh-agent@v0.10.0`, clearing the Node 20 deprecation warning for
+  every site that calls it. Its jobs run on `ubuntu-26.04` (ahead of the
+  `ubuntu-latest` migration).
+- **`docs_kit:install` scaffolds current toolchain floors.** The `package.json`
+  stub requires `tailwindcss`/`@tailwindcss/cli` `^4.3.3` and `daisyui`
+  `^5.7.47` (a spec keeps them in lockstep with the gem's own docs site), and
+  the generated `Dockerfile` installs Bun 1.4.2 (and falls back to Ruby 3.4.11
+  when the host Ruby version can't be read).
+- **`docs_kit:install` gitignores the generated `tailwind.sources.css`.**
+  `bin/build-css` rewrites it on every build with machine-specific gem paths, so
+  a committed copy only churns. `--sync` adds the `.gitignore` entry and warns
+  when the file is still tracked. (#72)
+- **`--sync` runs its first release migration** (1.1 → 1.2, above). The
+  migration registry no longer ships empty.
+
+### Fixed
+
+- **`docs_kit:page` injected the registry line once per group.** In a registry
+  laid out as blank-line-separated groups (the layout `docs_kit:install`
+  produces), the "page line not followed by a page line" Regexp anchor matched
+  the end of *every* group and Thor's `inject_into_file` replaced every match.
+  The anchor is now the file's last `page` line as a String, so one run adds
+  exactly one line, at the end of the last group.
+
+### Added
+
+- **`DocsUI::Code` infers the language from `filename:`.**
+  `DocsUI::Code(<<~YAML, filename: "config/deploy.yml")` now highlights as YAML
+  instead of Ruby: with no `lexer:`, the lexer is guessed from Rouge's filename
+  globs (`*.yml` → yaml, `Dockerfile` → docker, `*.sh` → shell, …). An explicit
+  `lexer:` still wins, and a block with neither (or an unguessable filename)
+  stays Ruby, so existing output is unchanged.
+
+## [1.1.1] and earlier
+
 ### Fixed
 
 - **SEO `og:image` 404.** The og:image tag pointed at the raw config path

data/README.md

@@ -102,9 +102,17 @@ A site created before the stamp existed (no comment) is treated as the earliest
 version, so it gets every migration. Migrations are **warn-only-safe** exactly
 like the drift report: what a step can't safely automate it prints as a manual
 checklist (`migration steps to apply by hand:`), never a destructive rewrite of
-a line you've edited. There are no migrations to apply yet — the mechanism ships
-ahead of the first release that needs one, so the upgrade path is already in
-place.
+a line you've edited. A value is only rewritten when it is exactly what an older
+docs-kit generated; anything you picked yourself is reported, never changed.
+
+Every release that needs site changes lists them under **"Upgrading from X.Y"**
+at the top of its [CHANGELOG](CHANGELOG.md) entry. That's what `--sync` automates
+and what it leaves to you. Read it before a `bundle update docs-kit` that crosses
+a minor version.
+
+| Release | `--sync` does | You do |
+|---------|---------------|--------|
+| 1.2 | Raises the Bun and Tailwind/daisyUI floors that docs-kit generated. Warns about Ruby below 3.3, hand-picked older floors, and a deploy workflow pinned off `@main` | Move to Ruby >= 3.3 before updating. `git rm --cached` a tracked `tailwind.sources.css` |
 
 ### One-time cleanup for sites created before these landed
 
@@ -118,6 +126,7 @@ generators:
 | `app/helpers/icon_helper.rb` | docs-kit renders icons via rails_icons (`DocsUI::Icon`) | Delete the file. |
 | Hand-pinned docs-kit lines in `config/importmap.rb` | the engine auto-pins the `docs-nav` controller and its assets | Delete the manual `pin`/`pin_all_from` lines for docs-kit. |
 | `Dockerfile` stamped by an older docs-kit (`# docs-kit Dockerfile vX.Y.Z`) | docs-kit ships an optimized, multi-stage Dockerfile; a stale copy misses image-size wins | Diff yours against the current template (`lib/generators/docs_kit/install/templates/Dockerfile.tt` in the gem), adopt the changes or replace it. See [Upgrading your Dockerfile](#upgrading-your-dockerfile). |
+| `app/assets/stylesheets/tailwind.sources.css` committed to git | `bin/build-css` regenerates it on every build with machine-specific absolute gem paths — the committed copy churns per machine/Ruby and no build consumes it. The generator adds the `.gitignore` entry, but gitignoring doesn't untrack an already-committed copy. | `git rm --cached app/assets/stylesheets/tailwind.sources.css` and commit. |
 
 ### Upgrading your Dockerfile
 
@@ -184,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
@@ -422,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
@@ -433,6 +487,10 @@ DocsUI::Section("Add the gem", id: "add", description: …)  # title positional
 DocsUI::Code(source, lexer: :ruby, filename: "Gemfile")   # source positional
 ```
 
+`DocsUI::Code` infers the language from `filename:` (`config/deploy.yml` →
+YAML, `Dockerfile` → docker, `bin/setup.sh` → shell); `lexer:` overrides the
+guess, and with neither the block is highlighted as Ruby.
+
 For the two wrappers that take **no** positional argument — prose and a
 multi-language example — `DocsUI::Page` gives you lowercase helpers so a block
 needs no parens:
@@ -930,7 +988,7 @@ jobs:
 ```yaml
 service: <repo>
 image: zoolutions/<repo>
-minimum_version: 4.0.0        # dash 4: dash-proxy identity + in-place host migration
+minimum_version: 4.0.7        # dash 4.0.7: doctor stale-proxy recovery + registry credential fail-fast
 retain_containers: 2
 error_pages_path: public      # 502/503/504.html served during a deploy gap
 registry: { server: ghcr.io, username: mhenrixon, password: [DASH_REGISTRY_PASSWORD] }
@@ -1038,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
@@ -1082,17 +1176,21 @@ application.register("reactive", ReactiveController)
 
 ## Releasing (maintainers)
 
-Cut a release with the version-bumping Rake task — never `gem push` by hand:
+Cut a release with `bin/release`. Never `gem push` by hand:
 
 ```bash
-rake release[1.0.0]           # bump → build-verify → commit → push → GitHub Release
-rake release[1.1.0.rc1]       # a pre-release (auto-flagged --prerelease)
-rake release[1.0.0,force]     # delete + re-create an existing tag/release
+bin/release list              # last releases + what each bump would give
+bin/release --dry-run         # the version it would cut + the changes since the last tag
+bin/release                   # patch bump (minor / major / 1.3.0.rc1 for others)
+bin/release 1.2.0 --force     # delete + re-create an existing tag/release
 ```
 
-The task (on `main`, clean tree only) bumps `lib/docs_kit/version.rb`, updates the
-lockfiles (incl. `docs/Gemfile.lock`), verifies `gem build --strict`, commits,
-pushes, and creates the GitHub Release. Publishing the tag fires
+`bin/release` checks you're on a clean, up-to-date `main`, confirms, and hands off
+to `rake release[X.Y.Z]` (`rakelib/release.rake`). That task bumps
+`lib/docs_kit/version.rb` and the `docs-kit` pin in `docs/Gemfile.lock` (in place,
+no re-resolve), verifies `gem build --strict`, commits, pushes, and creates the
+GitHub Release. Both files belong to the zoolutions release kit that every gem
+shares; see [RELEASE_KIT.md](RELEASE_KIT.md) to adopt or upgrade it elsewhere. Publishing the tag fires
 `.github/workflows/release.yml`, which runs the suite, rebuilds + content-checks
 the gem, signs it with Sigstore, and pushes to RubyGems over **OIDC trusted
 publishing** (no API token stored anywhere).

data/app/components/docs_ui/code.rb

@@ -9,12 +9,16 @@ module DocsUI
   # stylesheet asset is required.
   #
   #   render DocsUI::Code.new(ruby_source)                          # ruby, no title
-  #   render DocsUI::Code.new(py, lexer: :python, filename: "a.py")  # any language
+  #   render DocsUI::Code.new(yaml, filename: "config/deploy.yml")  # yaml, inferred
+  #   render DocsUI::Code.new(py, lexer: :python, filename: "a.py")  # explicit wins
   #
-  # Any language Rouge knows (~200 lexers) works by its name or alias — python,
-  # go, rust, elixir, kotlin, swift, json, dockerfile, ... — no allowlist. Add
-  # friendly lexer aliases via DocsKit.configure (code_lexer_aliases). An unknown
-  # language falls back to plaintext (never raises). (Tab labels are a
+  # The language resolves in order: an explicit `lexer:`; a guess from the
+  # `filename:` (Rouge's own filename globs — *.yml → yaml, Dockerfile → docker,
+  # *.sh → shell, …); else ruby. Any language Rouge knows (~200 lexers) works by
+  # its name or alias — python, go, rust, elixir, kotlin, swift, json,
+  # dockerfile, ... — no allowlist. Add friendly lexer aliases via
+  # DocsKit.configure (code_lexer_aliases). An unknown language falls back to
+  # plaintext (never raises). (Tab labels are a
   # DocsUI::Example concern — set via code_language_labels, not here; Code has no
   # label, only a filename.)
   class Code < Phlex::HTML
@@ -22,7 +26,7 @@ module DocsUI
 
     FORMATTER = Rouge::Formatters::HTML.new
 
-    def initialize(source, lexer: :ruby, filename: nil)
+    def initialize(source, lexer: nil, filename: nil)
       @source = source.to_s.strip
       @lexer = lexer
       @filename = filename
@@ -66,11 +70,26 @@ module DocsUI
       end
     end
 
-    # Resolve @lexer to a Rouge lexer instance. Order: an explicit Rouge::Lexer
-    # class/instance passed through; a configured friendly alias; Rouge's own
-    # registry (name/alias); then the configured fallback (plaintext).
+    # Resolve the lexer to a Rouge lexer instance. Order: an explicit Rouge::Lexer
+    # class/instance passed through; an explicit name via a configured friendly
+    # alias → Rouge's own registry → the configured fallback (plaintext); with no
+    # `lexer:` given, a guess from the filename; else the ruby default.
     def lexer
-      explicit_lexer || (find_lexer(@lexer.to_s) || Rouge::Lexers::PlainText).new
+      explicit_lexer ||
+        (@lexer && (find_lexer(@lexer.to_s) || Rouge::Lexers::PlainText).new) ||
+        guessed_lexer ||
+        Rouge::Lexers::Ruby.new
+    end
+
+    # A lexer inferred from @filename via Rouge's declared filename globs, or nil
+    # when there is no filename, nothing matches, or the match is ambiguous.
+    # (Lexer.guesses, not Lexer.guess: the latter answers PlainText for a
+    # no-match, which is indistinguishable from a real guess.)
+    def guessed_lexer
+      return nil if @filename.nil?
+
+      guesses = Rouge::Lexer.guesses(filename: @filename.to_s)
+      guesses.size == 1 ? guesses.first.new : nil
     end
 
     # A Rouge::Lexer instance passed directly (class or instance), else nil.

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.