docs-kit 1.0.7 → 1.1.0

data/lib/docs_kit/snapshot.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module DocsKit
+  # Reads a committed Markdown snapshot of one documentation version back as the
+  # registry duck type the rest of the kit already speaks (#all / #from_slug /
+  # #nav_items), so an archived version renders through TODAY's chrome — only
+  # the content is frozen.
+  #
+  # A snapshot lives at <config.snapshots_path>/<version id>/: a manifest.json
+  # describing the nav structure (see the schema in the snapshot task) plus one
+  # .md file per page, written by the host-run `bin/rails docs_kit:snapshot[id]`
+  # task at release time.
+  #
+  # A missing directory or unreadable manifest degrades to an EMPTY snapshot
+  # (no pages) — a version configured before its snapshot is written must never
+  # take the site down. The install generator's --sync report warns about the
+  # drift instead.
+  class Snapshot
+    # The manifest format this reader understands; the writer stamps it so a
+    # future format change is detectable rather than silently misread.
+    SCHEMA = 1
+
+    class << self
+      # The snapshot for this version, memoized per [version id, directory] and
+      # invalidated when manifest.json's mtime changes — the same
+      # reload-on-change posture as Configuration#openapi_document, so editing
+      # a snapshot in development is picked up without a server restart.
+      def for(version, config: DocsKit.configuration)
+        version = DocVersion.from(version)
+        root = root_for(version, config)
+        mtime = manifest_mtime(root)
+        key = [version.id.to_s, root.to_s]
+
+        @cache ||= {}
+        cached = @cache[key]
+        return cached.fetch(:snapshot) if cached && cached.fetch(:mtime) == mtime
+
+        new(version: version, root: root).tap do |snapshot|
+          @cache[key] = { snapshot: snapshot, mtime: mtime }
+        end
+      end
+
+      def reset_cache!
+        @cache = {}
+      end
+
+      private
+
+      # <snapshots_path>/<id>, or nil when no snapshots path resolves (no
+      # config, no Rails) — which reads back as an empty snapshot.
+      def root_for(version, config)
+        base = config.snapshots_path
+        return if base.nil?
+
+        Pathname.new(base).join(version.id.to_s)
+      end
+
+      def manifest_mtime(root)
+        return if root.nil?
+
+        path = root.join("manifest.json")
+        path.file? ? path.mtime : nil
+      rescue StandardError
+        nil
+      end
+    end
+
+    attr_reader :version, :root
+
+    def initialize(version:, root:)
+      @version = version
+      @root = root
+      @manifest = read_manifest
+    end
+
+    # Every snapshot page across the manifest's registries, in manifest order —
+    # each a Snapshot::Entry quacking like a Registry::Entry.
+    def all
+      registries.flat_map { |registry| registry.fetch(:entries) }
+    end
+
+    def from_slug(slug)
+      all.find { |entry| entry.slug.to_s == slug.to_s }
+    end
+
+    # { group => [NavItem] }, the Registry.nav_items shape — hrefs already carry
+    # the version prefix, so the Sidebar's strict path == href active-matching
+    # works unchanged.
+    def nav_items
+      nav_items_for(all)
+    end
+
+    # { heading => { group => [NavItem] } }, the Configuration#nav_groups shape,
+    # from the manifest's per-registry headings — a heading with no pages is
+    # dropped so the sidebar never shows an empty group.
+    def nav_groups
+      registries.each_with_object({}) do |registry, acc|
+        items = nav_items_for(registry.fetch(:entries))
+        acc[registry.fetch(:heading)] = items unless items.empty?
+      end
+    end
+
+    # The version-prefixed docs prefix (e.g. "/1.0/docs").
+    def path_prefix
+      "#{version.path_prefix}/docs"
+    end
+
+    # The raw Markdown body of the page with this slug, or nil when unknown.
+    def markdown_for(slug)
+      from_slug(slug)&.markdown
+    end
+
+    private
+
+    # The manifest's registries as { heading:, entries: [Snapshot::Entry] }.
+    def registries
+      @registries ||= Array(@manifest && @manifest["registries"]).map do |registry|
+        prefix = registry["path_prefix"] || "/docs"
+        {
+          heading: registry["heading"],
+          entries: Array(registry["pages"]).map do |attrs|
+            Entry.new(attrs, version: version, root: root, registry_prefix: prefix)
+          end
+        }
+      end
+    end
+
+    def nav_items_for(entries)
+      entries.group_by(&:group).transform_values do |grouped|
+        grouped.map { |entry| NavItem.new(href: entry.href, label: entry.title, icon: entry.icon) }
+      end
+    end
+
+    # The parsed manifest Hash, or nil (→ empty snapshot) when the directory or
+    # manifest is missing/unreadable — degrade, never raise (the site must stay
+    # up with a version configured before its snapshot exists).
+    def read_manifest
+      return if root.nil?
+
+      path = root.join("manifest.json")
+      return unless path.file?
+
+      JSON.parse(path.read)
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+  end
+end

data/lib/docs_kit/templates/new_site.rb

@@ -14,16 +14,16 @@ require "securerandom"
 #   * adds docs-kit + its runtime deps to the Gemfile,
 #   * runs `docs_kit:install` (all the Ruby/CSS/Stimulus wiring),
 #   * syncs the lucide icon set and builds the CSS,
-#   * scaffolds a deployable Kamal setup that calls docs-kit's reusable workflow.
+#   * scaffolds a deployable dash setup that calls docs-kit's reusable workflow.
 #
 # The generated app is a complete, deployable standalone docs site.
 
 # --- config the template reads ------------------------------------------------
 # DOCS_KIT_GEM_SOURCE lets the dogfood site (docs-kit/docs) depend on the gem via
 # path: ".." while a real new site depends on the released gem. Default: rubygems.
-gem_source = ENV.fetch("DOCS_KIT_GEM_SOURCE", "") # e.g. 'path: "..", ' or 'github: "mhenrixon/docs-kit", '
+gem_source = ENV.fetch("DOCS_KIT_GEM_SOURCE", "") # e.g. 'path: "..", ' or 'github: "zoolutions/docs-kit", '
 # The GHCR image/service = the OWNER/REPO the site will live in (repo-linked pkg).
-image = ENV.fetch("DOCS_KIT_IMAGE", "mhenrixon/#{app_name}")
+image = ENV.fetch("DOCS_KIT_IMAGE", "zoolutions/#{app_name}")
 service = ENV.fetch("DOCS_KIT_SERVICE", app_name)
 
 # --- gems ---------------------------------------------------------------------
@@ -53,14 +53,26 @@ after_bundle do
   run "bun install --silent" if system("command -v bun >/dev/null 2>&1")
   run "bun run build:css" if system("command -v bun >/dev/null 2>&1")
 
-  # --- deploy scaffolding (Kamal + the reusable workflow) ---------------------
+  # --- deploy scaffolding (dash + the reusable workflow) ---------------------
   create_file "config/deploy.yml", <<~YAML
-    # Kamal deploy → the oss-infrastructure server (Cloudflare Tunnel + kamal-proxy).
+    # dash deploy → the oss-infrastructure server (Cloudflare Tunnel + dash-proxy).
     # service/image = the repo OWNER/REPO so the ghcr package auto-links to the
     # repo and GITHUB_TOKEN can push + pull it (no PAT). See docs-kit's README.
+    # `dash docs` / `dash docs proxy` is the always-current reference for every key.
     service: #{service}
     image: #{image}
 
+    # dash 4 renamed the on-host proxy (kamal-proxy → dash-proxy) and migrates a
+    # host in place; an older CLI must not deploy this config.
+    minimum_version: 4.0.0
+
+    # A stateless docs site never rolls back far — keep the host tidy.
+    retain_containers: 2
+
+    # Status-named pages (public/502.html, 503, 504) the proxy serves in place of
+    # the app's during a deploy gap — paired with `proxy.intercept_errors` below.
+    error_pages_path: public
+
     servers:
       web:
         hosts:
@@ -72,17 +84,51 @@ after_bundle do
     proxy:
       host: <%= ENV["DEPLOY_DOMAIN"] %>
       app_port: 3000
+      # TLS terminates at Cloudflare; the tunnel reaches the proxy over plain HTTP.
       ssl: false
       healthcheck:
         path: /up
         interval: 5
         timeout: 30
 
+      # --- dash-proxy per-app features ------------------------------------------
+      # zstd / br / gzip negotiated at the edge; responses the app already encoded
+      # (Thruster) pass through untouched.
+      compress: true
+
+      # RFC 9111 shared cache. Only responses the app marks `Cache-Control: public,
+      # max-age` are stored (Propshaft assets, /llms*.txt) — HTML carrying a session
+      # cookie is refused by design. `dash proxy cache stats` shows what it holds.
+      cache:
+        enabled: true
+        max_ttl: 300
+
+      # Security headers set once here instead of per app; drop server fingerprints.
+      headers:
+        response:
+          set:
+            X-Content-Type-Options: nosniff
+            Referrer-Policy: strict-origin-when-cross-origin
+          remove:
+            - Server
+            - X-Powered-By
+
+      # Serve public/<status>.html instead of a bare "Bad Gateway" while a
+      # container is swapped or unhealthy.
+      intercept_errors:
+        - 502
+        - 503
+        - 504
+
+      # Keep the health probe out of the request histograms.
+      exclude_metrics_paths:
+        - /up
+
     registry:
       server: ghcr.io
       username: mhenrixon
       password:
-        - KAMAL_REGISTRY_PASSWORD
+        - DASH_REGISTRY_PASSWORD
 
     builder:
       arch: amd64
@@ -98,18 +144,24 @@ after_bundle do
         SECRET_KEY_BASE: "#{SecureRandom.hex(64)}"
   YAML
 
-  create_file ".kamal/secrets", <<~SH
+  # The status pages `proxy.intercept_errors` serves for a deploy gap — `rails new`
+  # ships 500.html; the proxy looks for the exact status it intercepted.
+  %w[502 503 504].each do |status|
+    create_file "public/#{status}.html", File.read("public/500.html") if File.exist?("public/500.html")
+  end
+
+  create_file ".dash/secrets", <<~SH
     # In CI the deploy workflow sets this to the job's GITHUB_TOKEN. Locally,
-    # export it (e.g. KAMAL_REGISTRY_PASSWORD=$(gh auth token)).
-    KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
+    # export it (e.g. DASH_REGISTRY_PASSWORD=$(gh auth token)).
+    DASH_REGISTRY_PASSWORD=$DASH_REGISTRY_PASSWORD
   SH
 
   # The Dockerfile + .dockerignore are written by `docs_kit:install` (run above in
   # after_bundle) so a scaffolded site and an upgrading site share ONE optimized,
   # version-stamped Dockerfile — no divergent copy to maintain here. The generator
   # derives the LABEL service from the app dir basename (= app_name); if the site
-  # deploys under a DIFFERENT Kamal service (`--service`), correct the label to
-  # match config/deploy.yml so Kamal's --skip-push validate_image passes.
+  # deploys under a DIFFERENT dash service (`--service`), correct the label to
+  # match config/deploy.yml so dash's --skip-push validate_image passes.
   gsub_file "Dockerfile", /LABEL service=".*"/, %(LABEL service="#{service}") if service != app_name
 
   create_file ".github/workflows/deploy-docs.yml", <<~YAML
@@ -120,7 +172,7 @@ after_bundle do
       workflow_dispatch:
     jobs:
       deploy:
-        uses: mhenrixon/docs-kit/.github/workflows/deploy.yml@main
+        uses: zoolutions/docs-kit/.github/workflows/deploy.yml@main
         with:
           image: #{image}
           service: #{service}

data/lib/docs_kit/version.rb

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

data/lib/docs_kit.rb

@@ -58,6 +58,9 @@ loader.ignore(File.expand_path("docs_kit/configuration.rb", __dir__))
 # ignore it here too or zeitwerk double-manages the constant.
 loader.ignore(File.expand_path("docs_kit/seo_config.rb", __dir__))
 loader.ignore(File.expand_path("docs_kit/landing_config.rb", __dir__))
+# Required eagerly by landing_config.rb (the LandingConfig::Logo alias resolves
+# it at require time, before this loader is set up), so ignore it here too.
+loader.ignore(File.expand_path("docs_kit/brand_logo.rb", __dir__))
 # Loaded ONLY by the host's docs_kit:og rake task (an explicit require), never at
 # gem runtime — so its Rack/browser tooling is never pulled into a host that
 # doesn't run the task. Ignore it so eager_load! doesn't require it.

data/lib/generators/docs_kit/install/install_generator.rb

@@ -568,7 +568,7 @@ module DocsKit
         (name || File.basename(destination_root)).to_s.underscore.humanize
       end
 
-      # The Kamal `service` name stamped as the Dockerfile's LABEL — the app dir
+      # The dash `service` name stamped as the Dockerfile's LABEL — the app dir
       # basename (a docs site's repo name), matching the `docs-kit new` default.
       # Used in Dockerfile.tt via <%= docker_service %>.
       def docker_service

data/lib/generators/docs_kit/install/templates/Dockerfile.tt

@@ -7,7 +7,7 @@
 # `build` stage. Pair it with the shipped .dockerignore so the build context
 # stays small (no node_modules, .git, logs, specs, coverage).
 #
-# Build context is the app root; `docker build .` (Kamal: context: ".").
+# Build context is the app root; `docker build .` (dash: context: ".").
 
 ARG RUBY_VERSION=<%= ruby_version_arg %>
 FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
@@ -59,9 +59,9 @@ RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile && \
 # --- Final stage --------------------------------------------------------------
 FROM base
 
-# Kamal's validate_image greps this label on a --skip-push deploy; it must equal
+# dash's validate_image greps this label on a --skip-push deploy; it must equal
 # `service:` in config/deploy.yml. The reusable deploy workflow also stamps it,
-# but keeping it here means `docker build` alone produces a Kamal-valid image.
+# but keeping it here means `docker build` alone produces a dash-valid image.
 LABEL service="<%= docker_service %>"
 
 # Copy ONLY the built artifacts from the build stage: the installed bundle and
@@ -79,9 +79,9 @@ EXPOSE 3000
 <% if thruster? -%>
 # Thruster fronts Puma (HTTP caching + compression + X-Sendfile). It listens on
 # HTTP_PORT and proxies to Puma on TARGET_PORT (it sets PORT for the child, which
-# config/puma.rb reads). HTTP_PORT MUST be the port traffic is routed to (Kamal's
+# config/puma.rb reads). HTTP_PORT MUST be the port traffic is routed to (dash's
 # `app_port`, the EXPOSE above) — Thruster's default is 80, which the non-root
-# user can't reliably bind AND which kamal-proxy (app_port: 3000) would never
+# user can't reliably bind AND which dash-proxy (app_port: 3000) would never
 # route to, silently bypassing Thruster straight into Puma.
 ENV HTTP_PORT="3000" \
     TARGET_PORT="3001"

data/lib/generators/docs_kit/install/templates/agents_md.erb

@@ -8,7 +8,7 @@ reads it through the bundled `write-docs-page` skill. Edit freely — a
 <!-- BEGIN docs-kit -->
 ## Writing docs pages (docs-kit)
 
-<%= app_brand %> is a [docs-kit](https://github.com/mhenrixon/docs-kit) site: a
+<%= app_brand %> is a [docs-kit](https://github.com/zoolutions/docs-kit) site: a
 Phlex/daisyUI chrome where **every page is a `DocsUI::Page` subclass** and the
 sidebar, TOC, search, and Markdown twin come free. To document something, you
 scaffold a page, then write its `#content`. Never hand-write HTML or daisyUI

data/lib/generators/docs_kit/install/templates/dockerignore

@@ -40,6 +40,7 @@
 
 # CI / deploy / Docker meta — not part of the runtime image.
 /.github/
+/.dash/
 /.kamal/
 /Dockerfile*
 /.dockerignore

data/lib/generators/docs_kit/install/templates/docs_kit.rb.erb

@@ -21,6 +21,23 @@ Rails.application.config.to_prepare do
     # docs live under a subpath:
     # c.brand_href = "/docs"
 
+    # Your own mark in the topbar + sidebar header instead of the text brand
+    # (which stays the accessible name). Exactly ONE of these forms:
+    #   paths:  — inline path-d list; fills with currentColor, so the mark
+    #             recolors with the active theme (also `svg:` for one path)
+    #   markup: — a full <svg>…</svg> string, embedded verbatim (use
+    #             fill="currentColor" in it to stay theme-adaptive)
+    #   file:   — a .svg under this app (e.g. "app/assets/images/mark.svg"),
+    #             embedded inline at render — same currentColor advice
+    #   src:    — an image asset path/URL rendered as an <img>; note an <img>
+    #             canNOT inherit currentColor, so it won't adapt to the theme
+    # c.brand_logo = { paths: ["M4 2h9l5 5…Z"], viewbox: "0 0 81 45", label: "<%= app_brand %>" }
+
+    # On desktop (lg:) the pinned sidebar already shows the brand, so the topbar
+    # copy is a duplicate. :mobile_only hides the topbar brand at lg:; the
+    # default (:always) keeps it everywhere.
+    # c.topbar_brand = :mobile_only
+
     # Docs embedded in a bigger app? Add the way BACK to that app — a labeled
     # link rendered once in the topbar, right after the brand. brand_href is the
     # DOCS home (brand, sidebar, and the page masthead's "← Docs home" all

data/lib/generators/docs_kit/install/templates/skill.md.erb

@@ -5,7 +5,7 @@ description: "Write, add, or update a documentation page in this docs-kit site.
 
 # Write a docs page
 
-This is a [docs-kit](https://github.com/mhenrixon/docs-kit) site (<%= app_brand %>).
+This is a [docs-kit](https://github.com/zoolutions/docs-kit) site (<%= app_brand %>).
 Every page is a `DocsUI::Page` subclass; the shell, sidebar, "On this page" TOC,
 search, and the `.md` twin all come free. Your job is to scaffold a page and
 write its `#content` — never hand-write HTML or daisyUI markup.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.1.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -164,6 +164,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/components/docs_ui/archived_page.rb
 - app/components/docs_ui/brand_mark.rb
 - app/components/docs_ui/callout.rb
 - app/components/docs_ui/code.rb
@@ -175,6 +176,7 @@ files:
 - app/components/docs_ui/icon.rb
 - app/components/docs_ui/json_response.rb
 - app/components/docs_ui/landing.rb
+- app/components/docs_ui/logo.rb
 - app/components/docs_ui/markdown.rb
 - app/components/docs_ui/markdown_action.rb
 - app/components/docs_ui/meta_tags.rb
@@ -205,8 +207,10 @@ files:
 - lib/docs_kit/api_client.rb
 - lib/docs_kit/api_request.rb
 - lib/docs_kit/api_templates.rb
+- lib/docs_kit/brand_logo.rb
 - lib/docs_kit/configuration.rb
 - lib/docs_kit/controller.rb
+- lib/docs_kit/doc_version.rb
 - lib/docs_kit/engine.rb
 - lib/docs_kit/landing_config.rb
 - lib/docs_kit/llms_text.rb
@@ -224,11 +228,15 @@ files:
 - lib/docs_kit/open_api/schema.rb
 - lib/docs_kit/registry.rb
 - lib/docs_kit/rubocop.rb
+- lib/docs_kit/scope.rb
+- lib/docs_kit/scoping.rb
 - lib/docs_kit/search_hit.rb
 - lib/docs_kit/search_index.rb
 - lib/docs_kit/search_index/snippet.rb
 - lib/docs_kit/seo_config.rb
 - lib/docs_kit/shortcut.rb
+- lib/docs_kit/snapshot.rb
+- lib/docs_kit/snapshot/entry.rb
 - lib/docs_kit/templates/new_site.rb
 - lib/docs_kit/topbar_link.rb
 - lib/docs_kit/version.rb
@@ -258,13 +266,13 @@ files:
 - lib/generators/docs_kit/page/templates/page.rb.erb
 - lib/rubocop/cop/docs_kit/escaped_interpolation_in_heredoc.rb
 - lib/rubocop/cop/docs_kit/render_component_preferred.rb
-homepage: https://github.com/mhenrixon/docs-kit
+homepage: https://github.com/zoolutions/docs-kit
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/mhenrixon/docs-kit
-  changelog_uri: https://github.com/mhenrixon/docs-kit/blob/main/CHANGELOG.md
-  bug_tracker_uri: https://github.com/mhenrixon/docs-kit/issues
+  source_code_uri: https://github.com/zoolutions/docs-kit
+  changelog_uri: https://github.com/zoolutions/docs-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/zoolutions/docs-kit/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: