RubyGems - docs-kit - Versions diffs - 1.0.1 → 1.0.3 - Mend

docs-kit 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +21 -8
data/README.md +53 -12
data/app/components/docs_ui/meta_tags.rb +33 -30
data/lib/docs_kit/seo_config.rb +9 -7
data/lib/docs_kit/templates/new_site.rb +11 -40
data/lib/docs_kit/version.rb +1 -1
data/lib/generators/docs_kit/install/install_generator.rb +100 -10
data/lib/generators/docs_kit/install/sync_report.rb +28 -2
data/lib/generators/docs_kit/install/templates/Dockerfile.tt +96 -0
data/lib/generators/docs_kit/install/templates/dockerignore +57 -0
data/lib/generators/docs_kit/install/templates/docs_kit.rb.erb +6 -4
metadata +3 -3
data/app/assets/images/og/og.png +0 -0
data/app/assets/images/og/og.svg +0 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72b8c93e9a6c2896bb31bd9ba8aaaf8cf5692424ab84d92ca8e5817d1b85291c
-  data.tar.gz: bfc8a48ab90cbb0d62083f864fd8f188a645070b86bf4af1ff63c9a302160e99
+  metadata.gz: 4ede4d90b3f6ca240a59c5f13d14967a29cf8a806fa041a3c7edfe65adf1ed2c
+  data.tar.gz: 015f6f05b3d3b09581679810ae41b3486c2428dc219d2d47f32775a40b449759
 SHA512:
-  metadata.gz: 6d6846fbbe1169e4513a2061b298a15ae65281da4eacaf3486d34392ceb52ecfcff7542df8eb28c2f8d5ff2c3b443c0e75a8371019b524293a51e76fbd964e80
-  data.tar.gz: ee32039817d7e32af7b6a97e2abb2bed4ff5142974fe8e2c43f40949755343e8d6c96781d82603b61fa4794f92f3c24ef78832d33be0288c32c39308dfea1a64
+  metadata.gz: 2b315f74f9de60f0e02354b3e8e093a85d06c99dc6bc8e9d1f96ad9ac0abc0bf7fe0d5db37f716b68e1fac2daabcafae1bd69b5c22cf587d7068cfc3b27c3050
+  data.tar.gz: f7868334e630ce1ab3ec99c9fbcfd91fbb6302c0f999c4b87dfc1c04959cbd8aac7cfecb49623ba2e4f2557665dcd844439f1d69211c97d5baa2ba55ad7efd6e

data/CHANGELOG.md CHANGED Viewed

@@ -2,20 +2,33 @@
 ## [Unreleased]
+### 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.
 ### 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
   new `c.seo` config block (`DocsKit::SeoConfig`). Pages carry an authorable
-  `description "..."` (falling back to the page's `#lead`). docs-kit ships a
-  neutral 1200×630 default OG image, and installs a `docs_kit:og` rake task that
-  screenshots a site's OWN landing page into `app/assets/images/og/` (host-side
-  headless browser; never a gem runtime dependency). A guard spec keeps the
-  shipped default present. 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 + default image;
-  `docs-kit new` reminds the owner to run it. (#48)
+  `description "..."` (falling back to the page's `#lead`). The social-share image
+  is site content (not shipped by the gem): the `docs_kit:og` rake task screenshots
+  a site's OWN landing page into its `app/assets/images/og/` (host-side headless
+  browser; never a gem runtime dependency), and `c.seo.og_image` points at it.
+  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)
 - 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 CHANGED Viewed

@@ -92,6 +92,39 @@ 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. |
+| `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). |
+### Upgrading your Dockerfile
+The generator ships two Docker files:
+- **`.dockerignore`** is gem-owned — every `docs_kit:install` (or `--sync`) run
+  **refreshes** it, so you always get the current build-context excludes
+  (`node_modules`, `.git`, `log`, `tmp`, `spec`, `coverage`, …). It carries no
+  site-specific content, so overwriting it is safe.
+- **`Dockerfile`** is site-owned — the generator **never clobbers** it (you tune
+  packages, the `CMD`, extra build steps). Instead it stamps a version marker
+  (`# docs-kit Dockerfile v<VERSION>`) so `--sync` can tell you when yours is
+  stale relative to the gem's current template.
+When the site bundles `thruster` (a Rails 8 default), the generated Dockerfile
+fronts Puma with Thruster (`CMD ["./bin/thrust", "./bin/rails", "server"]`) for
+HTTP caching, compression, and X-Sendfile — and the generator scaffolds the
+`bin/thrust` binstub if the app lacks one, since the exec-form CMD needs the
+file to exist in the image. Thruster listens on the routed port
+(`HTTP_PORT=3000` — Kamal's `app_port`) and proxies to Puma on `TARGET_PORT=3001`.
+Without thruster in the *production* bundle (absent, or only in a
+development/test group that `BUNDLE_WITHOUT` excludes) the CMD falls back to
+plain `rails server` — never a thrust CMD that would crash at boot.
+When `--sync` reports your Dockerfile is behind, compare it against the shipped
+template and pull in the improvements (or replace it wholesale if you never
+customized it):
+```bash
+# The template path is printed by the generator; it lives in the installed gem:
+diff Dockerfile "$(bundle show docs-kit)/lib/generators/docs_kit/install/templates/Dockerfile.tt"
+```
 ## Configure (per site)
@@ -180,9 +213,9 @@ nothing still gets a valid minimal card, so this is fully backwards-compatible.
 ```ruby
 # config/initializers/docs_kit.rb
 c.seo.description  = "What these docs cover, in one sentence."
-c.seo.og_image     = "og/og.png"            # generated by `bin/rails docs_kit:og`
+c.seo.og_image     = "og/og.png"            # a path in YOUR app/assets/images/
 c.seo.twitter_site = "@your_handle"
-c.seo.site_url     = "https://docs.example.com"  # absolutizes og:image + canonical
+c.seo.site_url     = "https://docs.example.com"  # your canonical base URL
 # c.seo.robots     = "noindex, nofollow"    # keep a staging/private site out of search
 # c.seo.theme_color = "#0f172a"             # tints mobile browser chrome
 ```
@@ -199,19 +232,26 @@ class Views::Docs::Pages::Installation < DocsUI::Page
 end
 ```
-**The social-share image.** docs-kit ships a neutral 1200×630 default so
-`og:image` is never broken. Generate one from your **own** landing page — it
-screenshots `/` into `app/assets/images/og/{og,twitter,square}.png` — whenever the
-page changes materially:
+**The social-share image is your content, not the gem's.** docs-kit ships no OG
+image — your landing page isn't docs-kit's to render. Until you set `c.seo.og_image`,
+**no `og:image` tag is emitted** (a valid card, never a broken-image 404). Generate
+one from your **own** landing page — it screenshots `/` into
+`app/assets/images/og/{og,twitter,square}.png` — then point `og_image` at it:
 ```bash
 bin/rails docs_kit:og   # needs a headless browser: shot-scraper or chromium/chrome
 ```
-It's a documented, manual routine (never run at deploy time), so a machine without
-a browser is never blocked. A guard spec keeps the shipped default present. Set
-`DOCS_KIT_OG_URL` to shoot a deployed URL instead of booting locally, or
-`DOCS_KIT_SHOT` to force a specific browser CLI.
+`og_image` is a **logical asset path in your pipeline** (`"og/og.png"`), resolved
+through `image_url` to the digested `/assets/og/og-<digest>.png` URL Propshaft
+serves — never the raw path, which 404s. So the image must be **precompiled**
+(your Dockerfile's `assets:precompile` handles this at deploy); a configured
+`og_image` that isn't in the pipeline fails loudly at deploy, not silently in
+production. An absolute URL (`"https://cdn.example.com/card.png"`) is used verbatim.
+`docs_kit:og` is a documented, manual routine (never run at deploy time), so a
+machine without a browser is never blocked. Set `DOCS_KIT_OG_URL` to shoot a
+deployed URL instead of booting locally, or `DOCS_KIT_SHOT` to force a browser CLI.
 ### Custom nav (advanced)
@@ -744,8 +784,9 @@ and applies docs-kit's application template, which:
 - runs `rails g docs_kit:install` (initializers, controllers, a Doc registry, a
   sample guide page, the Bun/Tailwind build, the docs-nav Stimulus wiring),
 - syncs the lucide icons and builds the CSS,
-- scaffolds Kamal (`config/deploy.yml`, `.kamal/secrets`, `Dockerfile`) and a
-  thin `.github/workflows/deploy-docs.yml` that calls the reusable workflow.
+- scaffolds Kamal (`config/deploy.yml`, `.kamal/secrets`, an optimized
+  multi-stage `Dockerfile` + a `.dockerignore`) and a thin
+  `.github/workflows/deploy-docs.yml` that calls the reusable workflow.
 Then `cd my-docs && bin/dev`. Already have a Rails app? Run the install generator
 instead:

data/app/components/docs_ui/meta_tags.rb CHANGED Viewed

@@ -11,12 +11,15 @@ module DocsUI
   #
   # All free text (title, description, brand) is emitted as normal Phlex
   # attribute values, so Phlex escapes it — config free text is never trusted
-  # markup. og:image/og:url/canonical are absolutized against config.seo.site_url
-  # when set, else the request base URL; with neither, og:image degrades to its
-  # raw path and canonical/og:url are omitted (guarded like Shell#csp_nonce, so
-  # an isolated render or a request-less static build never raises).
+  # markup. The og:image is SITE content (nil by default → no og:image tag): a
+  # relative og_image is resolved through the SITE'S asset pipeline (image_url) to
+  # the DIGESTED /assets URL Propshaft serves — NOT the raw config path, which
+  # 404s; an absolute URL passes through. canonical/og:url come from
+  # config.seo.site_url, else the request URL; both are omitted off a request
+  # (guarded like Shell#csp_nonce, so an isolated render never raises).
   class MetaTags < Phlex::HTML
     include Phlex::Rails::Helpers::Request
+    include Phlex::Rails::Helpers::ImageURL
     # title:       the page title (nil on a page that sets none, e.g. the home
     #              page) — combined with config.title_suffix for og:title.
@@ -108,17 +111,37 @@ module DocsUI
       meta(name: "theme-color", content: seo.theme_color)
     end
-    # The og:image as an absolute-when-possible URL: an already-absolute
-    # og_image is returned as-is; a relative path is joined onto the resolved
-    # base (config.seo.site_url or the request base); with no base it degrades to
-    # the raw path so og:image is never empty.
+    # The og:image as an absolute URL a crawler can fetch, or nil to emit NO
+    # og:image (a valid card without an image — never a 404). nil when og_image is
+    # unset (the default). An already-absolute og_image passes through. A relative
+    # path is a logical asset in the SITE'S pipeline, resolved through image_url to
+    # the DIGESTED, host-qualified /assets URL Propshaft actually serves
+    # (https://host/assets/og/og-<digest>.png) — never the raw config path, which
+    # 404s. Off a request (an isolated render / static build) there is no asset
+    # pipeline to resolve a relative path, so we emit nothing rather than a
+    # guessed-and-wrong URL; a real app always renders with a view context.
     def og_image_url
       image = seo.og_image
       return if image.to_s.empty?
       return image if absolute?(image)
-      base = base_url
-      base ? "#{base}/#{image.delete_prefix('/')}" : image
+      resolve_asset(image)
+    end
+    # Resolve a logical asset path to its served (digested, host-qualified) URL via
+    # the Rails asset helper. nil when there's no view context (image_url delegates
+    # to view_context, which raises without one — the same seam Shell#csp_nonce
+    # guards), so an isolated render emits no og:image rather than raising.
+    #
+    # A configured-but-unresolvable og_image (asset missing / not precompiled)
+    # raises the pipeline's MissingAssetError — intended, NOT rescued: a broken
+    # og_image is a real misconfiguration that must surface at deploy time
+    # (assets:precompile runs before the app serves), not ship silently-broken
+    # social cards. A site with no card image leaves og_image nil (see #og_image_url).
+    def resolve_asset(path)
+      return unless view_context
+      image_url(path)
     end
     # The canonical/og:url for this page. From config.seo.site_url when set (its
@@ -132,28 +155,8 @@ module DocsUI
       request.original_url
     end
-    # The base URL for absolutizing a relative og:image: config.seo.site_url's
-    # origin, else the request base URL, else nil. site_url may include a path
-    # (for canonical); strip it to an origin so the image path joins cleanly.
-    def base_url
-      return origin_of(seo.site_url) if seo.site_url
-      return unless request?
-      request.base_url
-    end
     def absolute?(url) = url.to_s.match?(%r{\Ahttps?://}i)
-    # Just the scheme+host(+port) of a URL, dropping any path — so joining an
-    # image path onto it never doubles a path segment.
-    def origin_of(url)
-      uri = URI.parse(url)
-      port = uri.port && uri.default_port != uri.port ? ":#{uri.port}" : ""
-      "#{uri.scheme}://#{uri.host}#{port}"
-    rescue URI::InvalidURIError
-      url
-    end
     # True only when there's a live Rails view context AND a request on it — the
     # phlex-rails #request helper delegates to view_context, which raises without
     # one. Mirrors Shell#csp_nonce's guard so an isolated Phlex render (the specs,

data/lib/docs_kit/seo_config.rb CHANGED Viewed

@@ -22,18 +22,20 @@ module DocsKit
     # (DocsUI::Page derives a per-page value from #lead when a page sets none).
     attr_accessor :description
-    # The social-share image, as an asset path (resolved via the Rails asset
-    # helper) or an absolute URL → og:image / twitter:image. Defaults to the
-    # neutral image docs-kit ships at app/assets/images/og/og.png so og:image is
-    # never broken; a site regenerates its own with `bin/rails docs_kit:og`.
+    # The social-share image → og:image / twitter:image. Either a logical asset
+    # path in the SITE'S OWN pipeline (e.g. "og/og.png", resolved through
+    # image_url to the digested /assets URL Propshaft serves) or an absolute URL.
+    # The image is SITE content, not shipped by the gem — nil by default, so a
+    # site with no card image emits NO og:image (a valid card, never a 404).
+    # Generate one into app/assets/images/ with `bin/rails docs_kit:og`, then set
+    # this to its path.
     attr_accessor :og_image
     # The og:type. "website" for a docs site; a page could override to "article".
     attr_accessor :og_type
     # The twitter:card style. "summary_large_image" renders a full-width banner
-    # (the shipped og:image is 1200×630, sized for it); "summary" is the small
-    # square card.
+    # (size your og:image 1200×630 for it); "summary" is the small square card.
     attr_accessor :twitter_card
     # The site's @handle → twitter:site, and the content author's → twitter:creator.
@@ -64,7 +66,7 @@ module DocsKit
     def initialize
       @description     = nil
-      @og_image        = "og/og.png"
+      @og_image        = nil
       @og_type         = "website"
       @twitter_card    = "summary_large_image"
       @twitter_site    = nil

data/lib/docs_kit/templates/new_site.rb CHANGED Viewed

@@ -4,7 +4,10 @@ require "securerandom"
 # Rails application template for a docs-kit docs site. Run via:
 #
-#   rails new my-docs --minimal -a propshaft -j importmap --skip-... -m new_site.rb
+#   rails new my-docs -a propshaft -j importmap --skip-... -m new_site.rb
+#
+# (NOT --minimal — that strips JS the shell needs AND the thruster gem the
+# generated Dockerfile fronts Puma with; exe/docs-kit passes the right flags.)
 #
 # or, more simply, via the `docs-kit new` CLI (exe/docs-kit) which supplies the
 # right `rails new` flags. It:
@@ -101,45 +104,13 @@ after_bundle do
     KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
   SH
-  create_file "Dockerfile", <<~DOCKER
-    # syntax = docker/dockerfile:1
-    ARG RUBY_VERSION=3.4.2
-    FROM ruby:$RUBY_VERSION-slim AS base
-    ARG BUN_VERSION=1.3.2
-    ENV BUN_INSTALL="/usr/local/bun"
-    ENV PATH="/usr/local/bun/bin:$PATH"
-    WORKDIR /rails
-    ENV BUNDLE_WITHOUT="development:test" RAILS_ENV="production"
-    RUN apt-get update -qq && \\
-        apt-get install --no-install-recommends -y curl libjemalloc2 && \\
-        rm -rf /var/lib/apt/lists /var/cache/apt/archives
-    RUN gem update --system --no-document && gem install -N bundler
-    FROM base AS build
-    RUN apt-get update -qq && \\
-        apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config unzip
-    RUN curl -fsSL https://bun.sh/install | bash -s "bun-v${BUN_VERSION}"
-    COPY Gemfile Gemfile.lock ./
-    RUN bundle install && rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache
-    COPY . .
-    RUN bun install --frozen-lockfile
-    # assets:precompile runs bun run build:css via the css:build rake enhance.
-    RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile
-    FROM base
-    # Kamal verifies this label on --skip-push deploy; must equal `service:`.
-    LABEL service="#{service}"
-    COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
-    COPY --from=build /rails /rails
-    RUN groupadd --system --gid 1000 rails && \\
-        useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \\
-        chown -R 1000:1000 /rails/log /rails/tmp
-    USER 1000:1000
-    EXPOSE 3000
-    CMD ["./bin/rails", "server", "-b", "0.0.0.0"]
-  DOCKER
+  # 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.
+  gsub_file "Dockerfile", /LABEL service=".*"/, %(LABEL service="#{service}") if service != app_name
   create_file ".github/workflows/deploy-docs.yml", <<~YAML
     name: Deploy docs

data/lib/docs_kit/version.rb CHANGED Viewed

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

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

@@ -4,6 +4,7 @@ require "erb"
 require "yaml"
 require "rails/generators/base"
 require_relative "sync_report"
+require_relative "../../../docs_kit/version"
 module DocsKit
   module Generators
@@ -168,18 +169,57 @@ module DocsKit
         create_file "app/assets/builds/.keep", ""
       end
-      # The SEO social-share image routine: the `docs_kit:og` rake task (gem-owned
-      # wiring, refreshed on every run so a site gets task fixes) plus the neutral
-      # default OG image (site content — `copy_file` skips it if the site already
-      # generated/customized its own, so `bin/rails docs_kit:og` output is never
-      # clobbered). c.seo.og_image defaults to "og/og.png" so a site's og:image is
-      # valid immediately, before it runs the task.
+      # Install the `docs_kit:og` rake task — gem-owned wiring, refreshed on every
+      # run so a site picks up task fixes. It does NOT ship an OG image: the
+      # social-share image is SITE content, generated into the site's OWN
+      # app/assets/images/ by `bin/rails docs_kit:og`. Until a site runs it (and
+      # sets c.seo.og_image), no og:image tag is emitted — a valid card, never a
+      # 404 for an image the gem can't provide.
       def create_og_task
         template "docs_kit_og.rake", "lib/tasks/docs_kit_og.rake"
-        copy_file(
-          File.expand_path("../../../../app/assets/images/og/og.png", __dir__),
-          "app/assets/images/og/og.png"
-        )
+      end
+      # The production Dockerfile — a lean multi-stage build for a standalone
+      # docs site. Site-customizable (a site tunes packages/CMD), so skip when it
+      # exists and point an upgrader at the current template for a manual diff.
+      # The template stamps a `# docs-kit Dockerfile vX.Y.Z` marker so a `--sync`
+      # upgrade (SyncReport) can flag a stale copy. (create_initializer follows
+      # this same skip-if-exists + template-hint pattern.)
+      def create_dockerfile
+        dockerfile = "Dockerfile"
+        if File.exist?(File.join(destination_root, dockerfile))
+          template_path = File.join(self.class.source_root, "Dockerfile.tt")
+          return say_status(:skip, "#{dockerfile} exists — compare with #{template_path} if upgrading", :blue)
+        end
+        template "Dockerfile.tt", dockerfile
+      end
+      # The .dockerignore — gem-owned build-context trimming (node_modules, .git,
+      # logs, specs, coverage). Refreshed on every run (like create_og_task): it
+      # carries no site-specific content, so a re-run always ships the current
+      # excludes rather than fossilizing an old list.
+      def create_dockerignore
+        copy_file "dockerignore", ".dockerignore", force: true
+      end
+      # When the site bundles thruster but lacks the binstub, create it — the
+      # Dockerfile's exec-form `CMD ["./bin/thrust", ...]` needs the file to EXIST
+      # in the image (`bundle install` installs the gem, not app binstubs, and
+      # `COPY . .` can't ship a file the repo doesn't have). Without this, the
+      # image builds green and the container crashes at boot. Skip-if-exists: a
+      # hand-tuned binstub is never touched.
+      def create_thrust_binstub
+        return unless gemfile_bundles_thruster? && !thrust_binstub?
+        create_file "bin/thrust", <<~RUBY
+          #!/usr/bin/env ruby
+          require "rubygems"
+          require "bundler/setup"
+          load Gem.bin_path("thruster", "thrust")
+        RUBY
+        chmod "bin/thrust", 0o755
       end
       def wire_assets_and_package_json
@@ -456,6 +496,56 @@ module DocsKit
         name = defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.class&.module_parent_name
         (name || File.basename(destination_root)).to_s.underscore.humanize
       end
+      # The Kamal `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
+        File.basename(destination_root)
+      end
+      # The RUBY_VERSION build ARG default: the host's running Ruby (X.Y.Z), so a
+      # site's image matches its dev Ruby. Used in Dockerfile.tt.
+      def ruby_version_arg
+        RUBY_VERSION[/\d+\.\d+\.\d+/] || "3.4.2"
+      end
+      # True when the site bundles Thruster (HTTP caching + compression +
+      # X-Sendfile in front of Puma) — a Rails 8 `rails new` ships bin/thrust +
+      # the gem, but docs_kit:install also runs on older apps where a thrust CMD
+      # would crash the container at boot (Gem.bin_path raises). Decides which
+      # CMD Dockerfile.tt emits. A committed binstub is authoritative; otherwise
+      # the Gemfile decides (and create_thrust_binstub scaffolds the binstub).
+      def thruster?
+        thrust_binstub? || gemfile_bundles_thruster?
+      end
+      def thrust_binstub?
+        File.exist?(File.join(destination_root, "bin/thrust"))
+      end
+      # True when the Gemfile declares thruster where the PRODUCTION bundle sees
+      # it. The Dockerfile sets BUNDLE_WITHOUT="development:test", so a
+      # `group :development do ... end` entry (or an inline `group:` kwarg) must
+      # NOT count — the gem wouldn't be installed and thrust would raise at boot.
+      # Line-level block tracking: any `... do` pushes, `end` pops; a gem line
+      # counts only outside every group block (nested non-group blocks are fine).
+      def gemfile_bundles_thruster?
+        gemfile = File.join(destination_root, "Gemfile")
+        return false unless File.exist?(gemfile)
+        block_stack = []
+        File.foreach(gemfile) do |line|
+          if line.match?(/\bdo\s*(\|[^|]*\|)?\s*$/)
+            block_stack.push(line.match?(/^\s*group\b/))
+          elsif line.match?(/^\s*end\b/)
+            block_stack.pop
+          elsif block_stack.none? && line.match?(/^\s*gem\s+["']thruster["']/) && !line.match?(/\bgroup:/)
+            return true
+          end
+        end
+        false
+      end
     end
   end
 end

data/lib/generators/docs_kit/install/sync_report.rb CHANGED Viewed

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+require_relative "../../../docs_kit/version"
 module DocsKit
   module Generators
     # Detects manual drift in an existing docs site that the install generator
@@ -9,13 +11,21 @@ module DocsKit
     # generator prints these as a checklist during a `--sync` upgrade; the site
     # owner deletes the flagged code by hand.
     #
-    # Two drift items, both from the consumer audits:
+    # Drift items, from the consumer audits:
     #   - ApplicationController hand-defines `render_page` — DocsKit::Controller
     #     (included by the generator for months) already provides it.
     #   - a dead IconHelper copy — the gem renders icons via rails_icons.
+    #   - a Dockerfile stamped by an OLDER docs-kit than the gem now ships — the
+    #     site should diff against the current template and adopt the improvements.
     class SyncReport
       APPLICATION_CONTROLLER = "app/controllers/application_controller.rb"
       ICON_HELPER = "app/helpers/icon_helper.rb"
+      DOCKERFILE = "Dockerfile"
+      # Matches the version stamp the Dockerfile template writes, e.g.
+      # `# docs-kit Dockerfile v1.0.2`. Absent on a hand-written Dockerfile a site
+      # brought itself — which we deliberately leave alone (no marker → no warning).
+      DOCKERFILE_MARKER = /docs-kit Dockerfile v(\d+\.\d+\.\d+)/
       def initialize(destination_root)
         @root = destination_root
@@ -24,7 +34,7 @@ module DocsKit
       # The drift messages, in the order a site should act on them. Empty when
       # the site is clean.
       def items
-        [render_page_drift, icon_helper_drift].compact
+        [render_page_drift, icon_helper_drift, dockerfile_drift].compact
       end
       def clean?
@@ -53,6 +63,22 @@ module DocsKit
           "rails_icons (DocsUI::Icon); delete it."
       end
+      # The site's Dockerfile carries a docs-kit version stamp OLDER than the gem
+      # now ships. We never rewrite the site's Dockerfile (it's tuned per site) —
+      # we point the owner at the current template to diff or replace. A file with
+      # no marker (a hand-written Dockerfile) is left alone: no stamp, no warning.
+      def dockerfile_drift
+        source = read(DOCKERFILE)
+        stamped = source&.match(DOCKERFILE_MARKER)
+        return unless stamped
+        site_version = stamped[1]
+        return if site_version == DocsKit::VERSION
+        "#{DOCKERFILE} is v#{site_version}, docs-kit now ships v#{DocsKit::VERSION} — " \
+          "diff against the template (bin/rails g docs_kit:install shows the path) and adopt the changes."
+      end
       def read(rel)
         path = File.join(@root, rel)
         File.exist?(path) ? File.read(path) : nil

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

@@ -0,0 +1,96 @@
+# syntax = docker/dockerfile:1
+# docs-kit Dockerfile v<%= DocsKit::VERSION %> — regenerate/diff: bin/rails g docs_kit:install
+#
+# A standalone docs-kit site: a lean, multi-stage production image. The final
+# stage carries only the runtime (Ruby + the installed bundle + the app), never
+# the build toolchain (build-essential, git, bun) — those live in the throwaway
+# `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: ".").
+ARG RUBY_VERSION=<%= ruby_version_arg %>
+FROM docker.io/library/ruby:$RUBY_VERSION-slim AS base
+# Rails app lives here.
+WORKDIR /rails
+ARG BUN_VERSION=1.3.2
+ENV BUN_INSTALL="/usr/local/bun" \
+    PATH="/usr/local/bun/bin:$PATH" \
+    BUNDLE_DEPLOYMENT="1" \
+    BUNDLE_PATH="/usr/local/bundle" \
+    BUNDLE_WITHOUT="development:test" \
+    RAILS_ENV="production"
+# Base packages the RUNTIME needs (jemalloc for a smaller/faster heap, curl for
+# the container healthcheck). Anything only the build needs goes in `build`.
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y curl libjemalloc2 && \
+    rm -rf /var/lib/apt/lists /var/cache/apt/archives
+# --- Build stage (throwaway — its layers never reach the final image) ---------
+FROM base AS build
+# Toolchain to compile native gems + fetch bun. Skip the apt cleanup: this whole
+# stage is discarded.
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config unzip
+RUN curl -fsSL https://bun.sh/install | bash -s -- "bun-v${BUN_VERSION}"
+# Install gems first (cached until Gemfile/Gemfile.lock change), then prune the
+# bundler cache + any git-sourced gem checkouts so they don't bloat the layer.
+COPY Gemfile Gemfile.lock ./
+RUN bundle install && \
+    rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache "${BUNDLE_PATH}"/ruby/*/bundler/gems/*/.git
+# Install JS deps (the Tailwind/daisyUI CLI), then the app.
+COPY package.json bun.lock* ./
+RUN bun install --frozen-lockfile
+COPY . .
+# assets:precompile runs `bun run build:css` via the css:build rake enhance.
+# Drop the node_modules + bun cache afterwards — the built CSS is all we keep.
+RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile && \
+    rm -rf node_modules .bun tmp/cache
+# --- Final stage --------------------------------------------------------------
+FROM base
+# Kamal'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.
+LABEL service="<%= docker_service %>"
+# Copy ONLY the built artifacts from the build stage: the installed bundle and
+# the app (with precompiled assets). No toolchain, no node_modules.
+COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
+COPY --from=build /rails /rails
+# Run as a non-root user; own only the runtime dirs it writes.
+RUN groupadd --system --gid 1000 rails && \
+    useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \
+    chown -R 1000:1000 /rails/log /rails/tmp
+USER 1000:1000
+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
+# `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
+# route to, silently bypassing Thruster straight into Puma.
+ENV HTTP_PORT="3000" \
+    TARGET_PORT="3001"
+CMD ["./bin/thrust", "./bin/rails", "server"]
+<% else -%>
+# No Thruster in this app's bundle — plain Puma. To front it with Thruster
+# (HTTP caching/compression/X-Sendfile): add `gem "thruster"`, then delete this
+# file and re-run `bin/rails g docs_kit:install` — the generator never
+# overwrites an existing Dockerfile, so a re-run alone won't update it. (It
+# also scaffolds the bin/thrust binstub the thrust CMD needs.)
+CMD ["./bin/rails", "server", "-b", "0.0.0.0"]
+<% end -%>

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

@@ -0,0 +1,57 @@
+# docs-kit .dockerignore — keep the build context (and image layers) small.
+# Gem-owned: `bin/rails g docs_kit:install` refreshes this on every run.
+# See https://docs.docker.com/build/building/context/#dockerignore-files
+# Git metadata — the app build never needs it (a released gem carries its files).
+/.git/
+/.gitignore
+/.gitattributes
+# Bundler config (BUNDLE_* env in the Dockerfile drives the install instead).
+/.bundle
+# Environment files and credentials — never bake secrets into an image.
+/.env*
+!/.env*.erb
+/config/master.key
+/config/credentials/*.key
+# Logs and tempfiles (keep the dirs, drop the contents).
+/log/*
+!/log/.keep
+/tmp/*
+!/tmp/.keep
+/tmp/pids/*
+!/tmp/pids/.keep
+# JS deps + generated assets: `bun install` + `assets:precompile` rebuild them.
+/node_modules/
+/app/assets/builds/*
+!/app/assets/builds/.keep
+# Generated by bin/build-css — Tailwind resolves the gem @source globs at build.
+/app/assets/stylesheets/tailwind.sources.css
+/public/assets
+# Tests + coverage — not needed to run the site in production.
+/spec/
+/.rspec
+/coverage/
+/spec/examples.txt
+# CI / deploy / Docker meta — not part of the runtime image.
+/.github/
+/.kamal/
+/Dockerfile*
+/.dockerignore
+# Editor + AI-assistant configs.
+/.claude/
+/.cursor/
+/.vscode/
+/.idea/
+/.ruby-lsp/
+/.solargraph.yml
+# Docs-kit's own tooling snapshots (harmless if absent in a consuming site).
+/codedb.snapshot
+/.worktrees/

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

@@ -36,19 +36,21 @@ Rails.application.config.to_prepare do
     # that sets none still gets a valid minimal card. Per-page descriptions come
     # from each page's `description "..."` (falling back to its lead paragraph).
     # c.seo.description     = "What these docs cover, in one sentence."
-    # c.seo.og_image        = "og/og.png"   # generated by `bin/rails docs_kit:og`
     # c.seo.twitter_card    = "summary_large_image"  # default; "summary" = small card
     # c.seo.twitter_site    = "@your_handle"
     # c.seo.twitter_creator = "@author_handle"
-    # c.seo.site_url        = "https://docs.example.com"  # absolutizes og:image/canonical off a request
+    # c.seo.site_url        = "https://docs.example.com"  # your canonical base URL
     # c.seo.locale          = "en_US"
     # c.seo.robots          = "noindex, nofollow"  # keep a staging/private site out of search
     # c.seo.favicon         = "/favicon.ico"
     # c.seo.theme_color     = "#0f172a"     # tints mobile browser chrome
     #
-    # Regenerate the social-share image from your OWN landing page (screenshots
-    # "/" into app/assets/images/og/) whenever it changes materially:
+    # The social-share image is YOUR content, not shipped by the gem. Generate one
+    # from your landing page (screenshots "/" into app/assets/images/og/) and point
+    # og_image at it — it's resolved through YOUR asset pipeline to the digested
+    # /assets URL. Until you set it, no og:image is emitted (a valid card, no 404).
     #   bin/rails docs_kit:og
+    # c.seo.og_image        = "og/og.png"   # a path in app/assets/images/
     # Code blocks use one Rouge theme by default. To keep them readable in BOTH
     # light and dark daisyUI themes, set a light base + a dark override — the dark

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -164,8 +164,6 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- app/assets/images/og/og.png
-- app/assets/images/og/og.svg
 - app/components/docs_ui/brand_mark.rb
 - app/components/docs_ui/callout.rb
 - app/components/docs_ui/code.rb
@@ -235,11 +233,13 @@ files:
 - lib/generators/docs_kit/install/USAGE
 - lib/generators/docs_kit/install/install_generator.rb
 - lib/generators/docs_kit/install/sync_report.rb
+- lib/generators/docs_kit/install/templates/Dockerfile.tt
 - lib/generators/docs_kit/install/templates/agents_md.erb
 - lib/generators/docs_kit/install/templates/application.tailwind.css.erb
 - lib/generators/docs_kit/install/templates/build-css
 - lib/generators/docs_kit/install/templates/build_css.rake
 - lib/generators/docs_kit/install/templates/doc.rb.erb
+- lib/generators/docs_kit/install/templates/dockerignore
 - lib/generators/docs_kit/install/templates/docs_controller.rb.erb
 - lib/generators/docs_kit/install/templates/docs_kit.rb.erb
 - lib/generators/docs_kit/install/templates/docs_kit_og.rake

data/app/assets/images/og/og.png DELETED Viewed

Binary file

data/app/assets/images/og/og.svg DELETED Viewed

@@ -1 +0,0 @@

- <svg height="630" viewBox="0 0 1200 630" width="1200" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><linearGradient id="a" x1="0" x2="1" y1="0" y2="1"><stop offset="0" stop-color="#0f172a"/><stop offset="1" stop-color="#1e293b"/></linearGradient><linearGradient id="b" x1="0" x2="1" y1="0" y2="0"><stop offset="0" stop-color="#38bdf8"/><stop offset="1" stop-color="#818cf8"/></linearGradient><path d="m0 0h1200v630h-1200z" fill="url(#a)"/><path d="m0 0h1200v8h-1200z" fill="url(#b)"/><path d="m80 470h240m-240 40h180m-180 40h220" fill="none" opacity=".5" stroke="#334155" stroke-width="2"/><g transform="translate(80 150)"><rect fill="url(#b)" height="96" rx="20" width="96"/><path d="m28 32h40m-40 16h40m-40 16h28" stroke="#0f172a" stroke-linecap="round" stroke-width="7"/></g><g font-family="Helvetica, Arial, sans-serif"><text fill="#f8fafc" font-size="88" font-weight="700" x="80" y="330">Documentation</text><text fill="#94a3b8" font-size="34" font-weight="400" x="82" y="392">Built with docs-kit</text></g></svg>