docs-kit 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6340fb386df08272f63e525ca81d43baaa1f440a82287e4a34e9a392b220a530
-  data.tar.gz: 3740655d5194976ea25a3ed3cdd6a633bb593c03c288a1c3a069d16d7c522cfe
+  metadata.gz: 29ec90ecec4c794dcfd2f0dfa7254a02844ccafa76019303b2b2bdbaf87c62c3
+  data.tar.gz: 3b8e8d345e6f795d00f44cea26529c9433eeb9ebb60e36cd07ce07541eec0fd5
 SHA512:
-  metadata.gz: 01e79925a8f67168a27e898fb13f6a9a5658b331b8a5b1ba854c9481c1afc5256f7ec89fb80a6e762f9ec0fd399425c38be82a1943a8fc9517e5cd0803e32fa4
-  data.tar.gz: a9a74e687605433c9a23069d6760a5a14093e898e0f64b133ede84f951f9f4deead0e98ad7735ca5a87e9f79ba86c9a340993004f1ece46731bda6016e6b9bab
+  metadata.gz: cb1ef7f9d6c3673f48d965b3bdd71c85b38b0f7c053d492078046f8fd37b094a98cb92ace7b6b777e986e00fd1cd2be187f455f591ab23437a9da8dee4ac31a6
+  data.tar.gz: 573e0e3db675e201e7457c8adee993d69e239789d08a3019b89c2409dd1cd6ec154e37fc6977c1a40e95369118ea78fa815e0e1da48ba4d551c6375a81692063

data/CHANGELOG.md

@@ -2,7 +2,48 @@
 
 ## [Unreleased]
 
-## [1.4.0]
+### Upgrading from 1.4
+
+Nothing to change for a site that registers the controller with
+`eagerLoadControllersFrom("docs_kit/controllers", application)`, as the
+generated `index.js` does: `docs-nav` still registers on every page. It is no
+longer preloaded, so on docs pages the eager loader's `import()` fetches it
+one request later instead of from the preload cache. To keep the preload, set
+`config.docs_kit.preload = true` in `config/application.rb`.
+
+### Added
+
+- **`config.docs_kit.controllers_under`** (default `"docs_kit/controllers"`)
+  sets the auto-pin's module namespace. `"controllers"` pins the controller as
+  `controllers/docs_nav_controller` (same asset), so the host's own loader for
+  `controllers` finds it, with no docs-kit line in `index.js`; with
+  `lazyLoadControllersFrom("controllers", application)` a page fetches it only
+  if it renders `data-controller="docs-nav"`. Set it in
+  `config/application.rb`. (#107)
+
+### Changed
+
+- **`docs-nav` is no longer preloaded on every page.** The auto-pin took
+  importmap-rails' default `preload: true`, so in a host whose docs share the
+  application's import map every page, docs or not, carried a
+  `<link rel="modulepreload">` for the 24 KB controller, and a host `pin` with
+  `preload: false` could not override it (a `pin_all_from` directory expands
+  over plain pins). `config.docs_kit.preload` (default `false`) is now the
+  pin's `preload:`: `true` restores 1.4's behaviour, an entry-point name
+  (importmap-rails 2.x) preloads it only where that entry point is rendered.
+  (#107)
+
+### Fixed
+
+- **One documented registration.** The README and the pin file's header now
+  point at one "Registering the controller" section. The README no longer
+  recommends `lazyLoadControllersFrom("docs_kit/controllers", application)`,
+  which in a host with its own controllers requests
+  `docs_kit/controllers/<identifier>_controller` for every host
+  `data-controller` and logs a "Failed to autoload controller" error for each,
+  on every page. (#107)
+
+## [1.4.0] — 2026-10-15
 
 ### Upgrading from 1.3
 
@@ -95,7 +136,15 @@ raises `FrozenError`; so does mutating one of docs-kit's constants.
   `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)
+## [1.2.1] — 2026-09-30
+
+### 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.
+
+## [1.2.0] — 2026-09-30 (tagged; never published to RubyGems)
 
 ### Upgrading from 1.1
 
@@ -130,9 +179,6 @@ bundle exec rspec
 
 ### 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
@@ -169,21 +215,68 @@ bundle exec rspec
   `lexer:` still wins, and a block with neither (or an unguessable filename)
   stays Ruby, so existing output is unchanged.
 
-## [1.1.1] and earlier
+## [1.1.1] — 2026-08-27
 
 ### Fixed
 
-- **SEO `og:image` 404.** The og:image tag pointed at the raw config path
-  (`https://site/og/og.png`), which isn't a served URL — Propshaft serves the
-  digested asset under `/assets`. A relative `og_image` is now resolved through
-  the site's asset pipeline (`image_url`) to the digested `/assets/og/og-<digest>.png`
-  URL, and the image is treated as **site content**: the gem ships none,
-  `c.seo.og_image` defaults to **nil** (unset → no og:image tag, never a 404), and
-  the `docs_kit:og` task writes into the *site's* `app/assets/images/`. Added a
-  booted-app integration test in the dogfood site
-  (`docs/test/integration/seo_meta_tags_test.rb`) that asserts og:image resolves
-  to a `/assets` URL that actually returns 200 — the coverage isolated component
-  specs can't provide.
+- **`/llms.txt` sends a public max-age** (`expires_in 300, public: true`), so
+  shared caches such as dash-proxy can store it; ETag revalidation is
+  unchanged. (#75)
+
+## [1.1.0] — 2026-08-27
+
+### Added
+
+- **Docs versions foundation.** `c.versions` (`DocsKit::DocVersion`),
+  `c.repo_url` and `c.snapshots_path`, a request-scoped version
+  (`DocsKit::Scope`) and a snapshot content source. A site that configures no
+  versions renders unchanged. (#67)
+
+### Changed
+
+- **The reusable deploy workflow uses dash 4.** `deploy.yml` installs
+  `dash ~> 4.0` and runs `dash doctor` before deploying; the registry secret is
+  now `DASH_REGISTRY_PASSWORD` (`KAMAL_REGISTRY_PASSWORD` is still exported),
+  and the `docs-kit new` deploy template turns on dash-proxy compression,
+  caching and security headers. (#74)
+
+### Fixed
+
+- **Repointed at the `zoolutions` org.** The reusable deploy workflow, the
+  `docs-kit new` and install templates, the README and the gemspec metadata
+  now reference `zoolutions/docs-kit` (reusable-workflow `uses:` refs don't
+  follow the repo move's redirect). (#70)
+
+## [1.0.8] — 2026-08-04
+
+### Added
+
+- **`c.brand_logo`.** A config-driven brand mark (`svg:`, `paths:`, `markup:`,
+  `file:` or `src:`) rendered by the new `DocsUI::Logo` in the topbar and
+  sidebar brand links, falling back to `c.brand`; `c.landing.logo` accepts the
+  same forms. `c.topbar_brand = :mobile_only` hides the topbar copy where the
+  sidebar brand is already visible. (#68)
+
+### Changed
+
+- **The sidebar's top-level heading is flattened.** With one nav heading it
+  is no longer rendered; with several, each is a static `menu-title` label and
+  only subgroups collapse. The landing doc index follows the same rule. (#66)
+
+## [1.0.7] — 2026-08-03
+
+### Added
+
+- **Version-aware `--sync` migrations.** Install and `--sync` stamp the
+  initializer with `# docs-kit synced: vX.Y.Z`, and `--sync` runs the ordered
+  migrations between that version and the gem's, printing what it can't
+  automate. The migration registry ships empty in 1.0.x. (#56)
+- **Two homes: `c.app_link`.** An opt-in `c.app_link = { href:, label: }`
+  renders a topbar link back to the hosting app, and the page masthead's link
+  now follows `c.brand_href` instead of the host's `root_path` and reads
+  "← Docs home". (#63)
+
+## [1.0.6] — 2026-07-04
 
 ### Added
 
@@ -194,6 +287,11 @@ bundle exec rspec
   site's asset pipeline). nil (the default) omits it, so it's backwards-compatible.
   This closes the gap a mounted docs app hit — a hero with no way to show the
   product's own logo — the first consumer to try `DocsUI::Landing` on a real site.
+
+## [1.0.5] — 2026-07-04
+
+### Added
+
 - **`DocsUI::Landing` — a config-driven marketing landing page.** Every consuming
   site (and this dogfood site) was hand-rolling a home page; now render
   `DocsUI::Landing` and drive it from a new `c.landing` config block
@@ -207,6 +305,48 @@ bundle exec rspec
   now renders it and the initializer documents `c.landing`. This is the first
   landing pattern proven on a **mounted** docs app (a docs section inside a larger
   Rails app whose `/` is already taken), contributed back from that use case.
+
+## [1.0.4] — 2026-07-04
+
+### Changed
+
+- **rouge 5 is allowed.** The dependency is now `>= 4.0, < 6`; the `< 5` cap
+  was downgrading sites already on rouge 5. (#54)
+
+### Fixed
+
+- **`docs_kit:install --sync` no longer re-injects the commented `/mcp` route
+  scaffold** into a site that already draws live MCP routes. (#53)
+
+## [1.0.3] — 2026-07-04
+
+### Added
+
+- **`docs_kit:install` templates a lean multi-stage `Dockerfile` and a
+  `.dockerignore`.** The `Dockerfile` is site-owned (skipped if present) and
+  carries a `# docs-kit Dockerfile vX.Y.Z` marker that `--sync` warns about
+  when it is older than the gem; `docs-kit new` uses the same template. (#52)
+
+## [1.0.2] — 2026-07-03
+
+### Fixed
+
+- **SEO `og:image` 404.** The og:image tag pointed at the raw config path
+  (`https://site/og/og.png`), which isn't a served URL — Propshaft serves the
+  digested asset under `/assets`. A relative `og_image` is now resolved through
+  the site's asset pipeline (`image_url`) to the digested `/assets/og/og-<digest>.png`
+  URL, and the image is treated as **site content**: the gem ships none,
+  `c.seo.og_image` defaults to **nil** (unset → no og:image tag, never a 404), and
+  the `docs_kit:og` task writes into the *site's* `app/assets/images/`. Added a
+  booted-app integration test in the dogfood site
+  (`docs/test/integration/seo_meta_tags_test.rb`) that asserts og:image resolves
+  to a `/assets` URL that actually returns 200 — the coverage isolated component
+  specs can't provide.
+
+## [1.0.1] — 2026-07-03
+
+### Added
+
 - **SEO + social sharing.** Every page now emits a complete SEO `<head>` —
   meta description, Open Graph, Twitter Card, canonical, favicon, robots, and
   theme-color — via the new `DocsUI::MetaTags` component, driven entirely by a
@@ -218,6 +358,11 @@ bundle exec rspec
   Backwards-compatible: a site that sets no `c.seo` renders a valid minimal card
   and its `<head>` is a strict superset of before. The install generator documents
   `c.seo` and installs the task; `docs-kit new` reminds the owner to run it. (#48)
+
+## [1.0.0] — 2026-07-03
+
+### Added
+
 - Release tooling matching the sibling gems (daisyui/phlex-reactive/pgbus): a
   `rake release[X.Y.Z]` task (version bump → lockfile update → build-verify →
   commit → push → GitHub Release; `pre`/`force` supported, `main`-only, clean-tree

data/README.md

@@ -124,7 +124,7 @@ generators:
 |-------|---------------|-----|
 | `ApplicationController#render_page` defined by hand | `DocsKit::Controller#render_page` is included (the generator injects `include DocsKit::Controller`) | Delete the method — keep the `include`. |
 | `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. |
+| 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. A line kept only to change `preload:` or `under:` becomes `config.docs_kit.preload` or `config.docs_kit.controllers_under` in `config/application.rb` (see [Registering the controller](#registering-the-controller)). |
 | `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. |
 
@@ -1123,12 +1123,74 @@ server round-trip:
   of three placements, auto-hiding on short pages. No server-side knowledge of
   the headings, no per-page wiring.
 
+### Registering the controller
+
+The engine pins `docs-nav` into the host's import map as
+`docs_kit/controllers/docs_nav_controller`, with no `<link rel="modulepreload">`
+on any page. Register it in `app/javascript/controllers/index.js` one of two
+ways.
+
+**Eager** — what `docs_kit:install` writes, next to the stock eager loader:
+
+```js
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
+eagerLoadControllersFrom("docs_kit/controllers", application)
+```
+
+It imports the controller on every page that loads the entry point, whether
+the page renders `docs-nav` or not. Right for a docs-only site, where every page
+renders the sidebar.
+
+**Through the host's own loader** — pin `docs-nav` under the host's
+`controllers` namespace instead, and add no docs-kit line to `index.js`:
+
+```ruby
+# config/application.rb
+config.docs_kit.controllers_under = "controllers"
+```
+
+The module becomes `controllers/docs_nav_controller` (same asset), so the
+host's existing `eagerLoadControllersFrom("controllers", application)` or
+`lazyLoadControllersFrom("controllers", application)` finds it by convention.
+With the lazy loader, a page fetches `docs-nav` only if it renders
+`data-controller="docs-nav"`: the setup for a host whose docs share an app with
+other pages. Drop an old `eagerLoadControllersFrom("docs_kit/controllers", ...)`
+line, which no longer matches anything. Don't keep a host file named
+`app/javascript/controllers/docs_nav_controller.js`: it has the same module
+name, and the host's `config/importmap.rb` is drawn after the engine's, so it
+replaces docs-kit's controller.
+
+> **Don't** call `lazyLoadControllersFrom("docs_kit/controllers", application)`
+> in a host with its own controllers. A lazy loader imports
+> `<under>/<identifier>_controller` for *every* `data-controller` on the page
+> that isn't registered yet, so `data-controller="dropdown"` makes it request
+> `docs_kit/controllers/dropdown_controller`, which isn't in the map: one
+> "Failed to autoload controller" console error per host identifier, on every
+> page. A second lazy loader is only safe on a namespace that owns every
+> identifier on the page.
+
+**Preloading.** `config.docs_kit.preload` (default `false`) is the pin's
+`preload:`. `true` puts a modulepreload for `docs-nav` on every page that renders
+the import map (docs-kit 1.4's behaviour). An entry-point name, such as
+`"docs"`, preloads it only on pages that render that entry point; it needs
+importmap-rails 2.x (1.x takes only `true`/`false`, and docs-kit doesn't check).
+
+```ruby
+# config/application.rb — defaults shown
+config.docs_kit.preload = false                         # true | "docs" | %w[docs admin]
+config.docs_kit.controllers_under = "docs_kit/controllers"
+```
+
+importmap-rails draws the pin in its own initializer, before
+`config/initializers/` run, so set both in `config/application.rb`. With
+`config.docs_kit.auto_pin = false` neither applies: the host owns the pin.
+
 ### 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:
+and map:
 
 ```ruby
 # config/application.rb — skip the engine's auto-pin into the shared map
@@ -1150,14 +1212,17 @@ 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"
+# This map only loads on docs pages, so preloading docs-nav here is the point.
 pin_all_from DocsKit::Engine.root.join("app/javascript/docs_kit/controllers"),
-             under: "docs_kit/controllers", to: "docs_kit/controllers"
+             under: "docs_kit/controllers", to: "docs_kit/controllers", preload: true
 ```
 
 `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)`.
+`docs` entry point registers the controller eagerly, as in
+[Registering the controller](#registering-the-controller). With one shared map,
+a `docs` entry point and `config.docs_kit.preload = "docs"` preload `docs-nav`
+on docs pages only, without a second map.
 
 ### On this page (auto-TOC)
 
@@ -1183,13 +1248,7 @@ headings, so they need zero per-page data. A page with fewer than 2 sections
 hides the TOC. Scroll-spy highlights the section you're reading.
 
 `DocsUI::Sidebar` already carries `data-controller="docs-nav"`. Register the
-controller in the host app:
-
-```js
-// app/javascript/controllers/index.js
-import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
-lazyLoadControllersFrom("docs_kit/controllers", application)
-```
+controller as in [Registering the controller](#registering-the-controller).
 
 The **active nav item** needs no JS — it's server-rendered from the request path.
 

data/config/importmap.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
-# Auto-pins the gem's bundled Stimulus controllers for importmap-rails consumers.
-# Exposes `docs_kit/controllers/docs_nav_controller`. Register it in the host app:
+# Auto-pins the gem's bundled Stimulus controller (docs-nav) for importmap-rails
+# consumers. With the defaults it is `docs_kit/controllers/docs_nav_controller`,
+# preloaded nowhere. Two engine options, set in the host's config/application.rb,
+# shape the pin:
 #
-#   // app/javascript/controllers/index.js
-#   import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
-#   eagerLoadControllersFrom("docs_kit/controllers", application)
+#   config.docs_kit.preload = false                         # true, or an entry point ("docs")
+#   config.docs_kit.controllers_under = "docs_kit/controllers"  # "controllers" rides the host's lazy loader
 #
-# Use eagerLoadControllersFrom (already imported in the default index.js), NOT
-# lazyLoadControllersFrom — the latter isn't imported there, so calling it throws
-# a ReferenceError that aborts the module and no controllers register at all.
+# How to register the controller in the host's controllers/index.js, and which
+# loader to avoid: README → "Registering the controller".
+docs_kit = DocsKit::Engine.config.docs_kit
 pin_all_from DocsKit::Engine.root.join("app/javascript/docs_kit/controllers"),
-             under: "docs_kit/controllers",
-             to: "docs_kit/controllers"
+             under: docs_kit.controllers_under,
+             to: "docs_kit/controllers",
+             preload: docs_kit.preload

data/lib/docs_kit/engine.rb

@@ -49,11 +49,22 @@ 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.
+    # Host-facing engine options, set in config/application.rb: importmap-rails
+    # draws the auto-pin in its own initializer, before config/initializers run.
+    # `config.docs_kit.auto_pin = false` 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
+    # The auto-pin's `preload:`. false (the default) keeps docs-nav out of every
+    # page's modulepreloads; true preloads it everywhere; an entry-point name (or
+    # an array, importmap-rails 2.x) preloads it only where that entry point loads.
+    config.docs_kit.preload = false
+    # The auto-pin's module namespace. "controllers" pins docs-nav as
+    # `controllers/docs_nav_controller`, so the host's own
+    # `lazyLoadControllersFrom("controllers", application)` loads it by convention
+    # on the pages that render it. The asset path never changes.
+    config.docs_kit.controllers_under = "docs_kit/controllers"
 
     # Auto-pin the controller for importmap-rails consumers, so a host app gets
     # `docs_kit/controllers/docs_nav_controller` with no manual pin.

data/lib/docs_kit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Mikael Henriksson