RubyGems - docs-kit - Versions diffs - 1.0.0 → 1.0.2 - Mend

docs-kit 1.0.0 → 1.0.2

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 (16) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +25 -0
data/README.md +51 -0
data/app/components/docs_ui/meta_tags.rb +166 -0
data/app/components/docs_ui/page.rb +14 -1
data/app/components/docs_ui/shell.rb +14 -4
data/lib/docs_kit/configuration.rb +11 -0
data/lib/docs_kit/og_generator.rb +167 -0
data/lib/docs_kit/seo_config.rb +81 -0
data/lib/docs_kit/templates/new_site.rb +3 -0
data/lib/docs_kit/version.rb +1 -1
data/lib/docs_kit.rb +7 -0
data/lib/generators/docs_kit/install/install_generator.rb +10 -0
data/lib/generators/docs_kit/install/templates/docs_kit.rb.erb +22 -0
data/lib/generators/docs_kit/install/templates/docs_kit_og.rake +44 -0
metadata +5 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee1f1a74269d5f9c8595eee3fe8c2275f9082a3f83f642671cb2227b6113fbf5
-  data.tar.gz: b1f465550e55b8ebc2159635706530391aa881f6cd6413fb4e0d71c79f810055
+  metadata.gz: df9e88e060d79197aaf8f9247000b31f5da3568bbf7099f18f59bc216b11e877
+  data.tar.gz: 1fde31a5d995087e06b62f2b58983e73acfc12309d6958db6e913f538894edbf
 SHA512:
-  metadata.gz: 4f2a568efb0a6a0766fb72065a0721976ff84968d49cbada10597700f53adb6db3b31ca73d17f022212d4ce7da474d499c7d14f54e2e284122cc2b1acebd5a69
-  data.tar.gz: 04a0e1a8fcaedcb330d7a35aa9a1fe7e799412795bd6062524d86834591d677fa5947fcf56c232f220b905fb0b4a5d2d6dc21de09d12615dafa0a5f0a2e9d5b1
+  metadata.gz: 8c8de40c603fa96e5fbee8aa377816894566c3b4f40c632e51d1a1055b875fe48b3349ef9cc833f0bada6b85d3504cfdc433ef27c9cdb9fff16ce30e81f0aa16
+  data.tar.gz: 7230b76a2e9d68d98061c92b2002ad59a2ca9a4609df75d8de2c68f4d911c78938188e1b87d1ced4c3ad7ff52ea4e9e6105fe8b0d2f43c27da826b77297f82fb

data/CHANGELOG.md CHANGED Viewed

@@ -2,8 +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`). 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

@@ -169,6 +169,57 @@ Any other `icon:` value is treated as a **lucide** name and rendered through
 sets nothing has an unchanged topbar. The marks use `fill: currentColor`, so they
 recolor with the active daisyUI theme like the rest of the chrome.
+### SEO & social sharing
+Every page ships a complete SEO `<head>` — a meta description, **Open Graph**,
+**Twitter Card**, canonical, favicon, and theme-color — so a link shared to
+Slack/Discord/X/LinkedIn renders a rich card instead of a bare URL. It's all
+config-driven (`DocsUI::MetaTags` reads `DocsKit.configuration`); a site that sets
+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"            # a path in YOUR app/assets/images/
+c.seo.twitter_site = "@your_handle"
+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
+```
+**Per-page descriptions.** A `DocsUI::Page` sets its own with `description "..."`;
+when it doesn't, the description is derived from the page's `#lead`, so existing
+pages get a sensible per-page description for free:
+```ruby
+class Views::Docs::Pages::Installation < DocsUI::Page
+  title       "Installation"
+  description "Add the gem and render your first component."  # optional
+  def lead = "..."   # used as the description when none is set
+end
+```
+**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
+```
+`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)
 Sites that interleave several registries under a heading, or need custom

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

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+module DocsUI
+  # The SEO / social-share <head> tags: description, Open Graph, Twitter Card,
+  # canonical, favicon, robots, theme-color. Rendered by DocsUI::Shell inside
+  # <head>, driven entirely by DocsKit.configuration (+ .seo) and the per-page
+  # title/description — so every docs site is share-ready with zero markup, and a
+  # site tunes it through config alone (no Shell subclass).
+  #
+  #   render DocsUI::MetaTags.new(title: "Installation", description: "…")
+  #
+  # All free text (title, description, brand) is emitted as normal Phlex
+  # attribute values, so Phlex escapes it — config free text is never trusted
+  # 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.
+    # description: the page's resolved description (DocsUI::Page passes its own
+    #              description or #lead); nil falls back to config.seo.description.
+    def initialize(title: nil, description: nil)
+      @title = title
+      @description = description
+    end
+    def view_template
+      description_meta
+      open_graph
+      twitter_card
+      canonical_link
+      favicon_link
+      robots_meta
+      theme_color_meta
+    end
+    private
+    def config = DocsKit.configuration
+    def seo = config.seo
+    # The page description, falling back to the site-wide default. nil → the
+    # description tags (meta description, og:description) are omitted.
+    def description = @description || seo.description
+    # 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(" · ")
+    end
+    def description_meta
+      return unless description
+      meta(name: "description", content: description)
+    end
+    # The always-present minimal OG block (title/type/site_name) plus the opt-in
+    # description/image/url. A site that configures nothing still gets a valid
+    # card — never a broken empty tag.
+    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)
+      open_graph_optional
+    end
+    # The OG tags emitted only when their value resolves — kept separate so the
+    # always-present block above stays a flat, obvious minimum.
+    def open_graph_optional
+      meta(property: "og:locale", content: seo.locale) if seo.locale
+      meta(property: "og:description", content: description) if description
+      meta(property: "og:image", content: og_image_url) if og_image_url
+      meta(property: "og:url", content: canonical_url) if canonical_url
+    end
+    def twitter_card
+      meta(name: "twitter:card", content: seo.twitter_card)
+      meta(name: "twitter:site", content: seo.twitter_site) if seo.twitter_site
+      meta(name: "twitter:creator", content: seo.twitter_creator) if seo.twitter_creator
+      meta(name: "twitter:image", content: og_image_url) if og_image_url
+    end
+    def canonical_link
+      return unless canonical_url
+      link(rel: "canonical", href: canonical_url)
+    end
+    def favicon_link
+      return unless seo.favicon
+      link(rel: "icon", href: seo.favicon)
+    end
+    def robots_meta
+      return unless seo.robots
+      meta(name: "robots", content: seo.robots)
+    end
+    def theme_color_meta
+      return unless seo.theme_color
+      meta(name: "theme-color", content: seo.theme_color)
+    end
+    # 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)
+      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
+    # path is honored verbatim so a site can point canonical at a specific URL),
+    # else the request's original URL. nil when neither is available (an isolated
+    # render), so canonical/og:url are simply omitted.
+    def canonical_url
+      return seo.site_url if seo.site_url
+      return unless request?
+      request.original_url
+    end
+    def absolute?(url) = url.to_s.match?(%r{\Ahttps?://}i)
+    # 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,
+    # a request-less static build) degrades cleanly instead of raising.
+    def request? = !view_context.nil? && !request.nil?
+  end
+end

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

@@ -36,6 +36,15 @@ module DocsUI
         @eyebrow
       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.
+      def description(value = nil)
+        @description = value if value
+        @description
+      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.
@@ -46,7 +55,11 @@ module DocsUI
     end
     def view_template
-      render DocsUI::Shell.new(title: self.class.title, on_page: self.class.on_page) do
+      render DocsUI::Shell.new(
+        title: self.class.title,
+        description: self.class.description || lead,
+        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

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

@@ -23,11 +23,16 @@ module DocsUI
     DRAWER_ID = "site-drawer"
-    # on_page: the auto-TOC placement for this page (:panel/:toggle/:sidebar or
-    # false). Threaded to the sidebar's docs-nav controller; :panel/:toggle also
-    # render an "On this page" slot inside the content column.
-    def initialize(title: nil, on_page: false)
+    # title:       the page title → <title> and og:title.
+    # description: the page description → the SEO/social meta tags (DocsUI::Page
+    #              passes its own description or #lead); nil falls back to
+    #              config.seo.description in DocsUI::MetaTags.
+    # on_page:     the auto-TOC placement for this page (:panel/:toggle/:sidebar or
+    #              false). Threaded to the sidebar's docs-nav controller;
+    #              :panel/:toggle also render an "On this page" slot in the content.
+    def initialize(title: nil, description: nil, on_page: false)
       @title = title
+      @description = description
       @on_page = DocsKit.configuration.normalize_on_page(on_page)
     end
@@ -72,6 +77,11 @@ module DocsUI
         title { [@title, config.title_suffix].compact.join(" · ") }
         meta(charset: "utf-8")
         meta(name: "viewport", content: "width=device-width,initial-scale=1")
+        # SEO / social-share tags (description, Open Graph, Twitter Card,
+        # canonical, favicon, robots, theme-color) from config.seo + this page's
+        # title/description. A site that sets no c.seo still gets a valid minimal
+        # OG block, so the head is a strict superset of the pre-SEO markup.
+        render DocsUI::MetaTags.new(title: @title, description: @description)
         csrf_meta_tags
         csp_meta_tag
         # Turbo morphs page-level navigations so a re-render preserves scroll and

data/lib/docs_kit/configuration.rb CHANGED Viewed

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+require_relative "seo_config"
 module DocsKit
   # Per-site configuration for the shared docs chrome. Everything that differs
   # between two otherwise-identical docs sites lives here, so the Phlex shell
@@ -270,6 +272,15 @@ module DocsKit
       Array(@topbar_links).map { |link| DocsKit::TopbarLink.from(link) }
     end
+    # The SEO / social-share knobs (DocsKit::SeoConfig), read by DocsUI::MetaTags.
+    # Lazily built and memoized so a `c.seo.description = ...` block mutates the
+    # one instance the Shell later reads. A site that never touches it gets the
+    # backwards-safe defaults (see SeoConfig), so the head is a strict superset of
+    # the pre-SEO markup.
+    def seo
+      @seo ||= DocsKit::SeoConfig.new
+    end
     # The loaded DocsKit::OpenApi::Document for #openapi. Memoized; when #openapi
     # is a file path, the memo is invalidated on an mtime change so editing the
     # spec in development is picked up without a server restart. Raises a

data/lib/docs_kit/og_generator.rb ADDED Viewed

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+require "shellwords"
+module DocsKit
+  # Screenshots a URL into the site's OG/Twitter images. Loaded ONLY by the
+  # host-installed `docs_kit:og` rake task (via an explicit require) — never at
+  # gem runtime — so the headless-browser tooling it drives is never a docs-kit
+  # dependency. zeitwerk ignores this file (see lib/docs_kit.rb) for the same
+  # reason: it must not be eager-loaded into a host that never runs the task.
+  #
+  # Usage (from the rake task):
+  #   DocsKit::OgGenerator.new(url:, out_dir:, sizes:, shooter:).call
+  #
+  # When #url is nil the generator boots the Rails app on an ephemeral port and
+  # shoots "/"; when set it shoots that URL directly (e.g. a deployed site). The
+  # shooter is a headless-browser CLI resolved at runtime: an explicit override,
+  # else the first of shot-scraper / chromium / chrome found on PATH.
+  class OgGenerator
+    # Raised when no supported headless-browser CLI is available. The message
+    # names each supported tool + how to install one, so the task fails with a
+    # fix, not a stack trace.
+    class NoShooterError < StandardError; end
+    # The shooters we know how to drive, in preference order. shot-scraper first
+    # (purpose-built, handles sizing cleanly); then a raw chromium/chrome.
+    SHOOTERS = %w[shot-scraper chromium chromium-browser google-chrome chrome].freeze
+    attr_reader :url, :out_dir, :sizes
+    def initialize(url:, out_dir:, sizes:, shooter: nil)
+      @url = url
+      @out_dir = out_dir.to_s
+      @sizes = sizes
+      @shooter = shooter
+    end
+    # The chosen shooter name (explicit override or nil until #resolve_shooter!).
+    def shooter_name = @shooter
+    # The full run: resolve a shooter, ensure the output dir, boot a local server
+    # if needed, and shoot every size. Returns the list of written paths.
+    def call
+      tool = resolve_shooter!
+      require "fileutils"
+      FileUtils.mkdir_p(out_dir)
+      with_target_url do |target|
+        sizes.map do |filename, dimensions|
+          path = File.join(out_dir, filename)
+          run(command_for(tool, target, dimensions, path))
+          path
+        end
+      end
+    end
+    # Resolve the shooter CLI: an explicit override (returned as-is so a user can
+    # force a specific tool), else the first supported binary on PATH. Raises
+    # NoShooterError naming the options when none is found.
+    def resolve_shooter!
+      return @shooter if @shooter && !@shooter.to_s.empty?
+      found = SHOOTERS.find { |cmd| which(cmd) }
+      return found if found
+      raise NoShooterError,
+            "No headless-browser CLI found. Install one of: shot-scraper " \
+            "(`pipx install shot-scraper && shot-scraper install`), chromium, or " \
+            "chrome — or set DOCS_KIT_SHOT to the command to use."
+    end
+    # Build the argv for `tool` to screenshot `target` at `[w, h]` into `path`.
+    # Kept pure (no side effects) so it's unit-testable without a browser.
+    def command_for(tool, target, dimensions, path)
+      width, height = dimensions
+      case tool
+      when "shot-scraper"
+        ["shot-scraper", target, "--width", width.to_s, "--height", height.to_s, "-o", path]
+      else # a chromium/chrome family binary
+        [
+          tool, "--headless=new", "--disable-gpu", "--hide-scrollbars",
+          "--force-device-scale-factor=1",
+          "--window-size=#{width},#{height}",
+          "--screenshot=#{path}", target
+        ]
+      end
+    end
+    private
+    # Yield the URL to shoot. If #url was given, shoot it directly. Otherwise boot
+    # the host Rails app on an ephemeral port, yield its local URL, and tear it
+    # down after. Rack/rackup are the host app's own deps (it's a Rails app), not
+    # docs-kit's — required lazily here so the gem never loads them.
+    def with_target_url(&)
+      return yield(url) if url && !url.to_s.empty?
+      boot_local_server(&)
+    end
+    # Boot the Rails app with Rack::Handler on an ephemeral port in a background
+    # thread, wait for it to answer, yield the URL, then shut down.
+    def boot_local_server
+      require "rack"
+      require "socket"
+      port = free_port
+      app = Rails.application
+      server_thread = Thread.new do
+        Rackup::Handler.get("webrick").run(app, Port: port, Host: "127.0.0.1", Logger: null_logger, AccessLog: [])
+      rescue LoadError
+        Rack::Handler.get("webrick").run(app, Port: port, Host: "127.0.0.1", Logger: null_logger, AccessLog: [])
+      end
+      wait_for_port(port)
+      yield "http://127.0.0.1:#{port}/"
+    ensure
+      server_thread&.kill
+    end
+    # An open ephemeral port (bind to 0, read it back, close). A tiny race window
+    # remains but is acceptable for a one-shot local screenshot server.
+    def free_port
+      server = TCPServer.new("127.0.0.1", 0)
+      port = server.addr[1]
+      server.close
+      port
+    end
+    # Poll until the local server accepts a connection (or give up after ~15s so a
+    # boot failure surfaces instead of hanging).
+    def wait_for_port(port, timeout: 15)
+      deadline = monotonic_now + timeout
+      loop do
+        TCPSocket.new("127.0.0.1", port).close
+        return
+      rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL
+        raise "docs_kit:og: local server did not start within #{timeout}s" if monotonic_now > deadline
+        sleep 0.2
+      end
+    end
+    def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    def null_logger
+      require "logger"
+      Logger.new(File::NULL)
+    end
+    # Run a command, raising with the joined argv on a non-zero exit so a shooter
+    # failure is loud (not a silently-missing image).
+    def run(argv)
+      ok = system(*argv)
+      raise "docs_kit:og: screenshot command failed: #{argv.shelljoin}" unless ok
+    end
+    # Locate an executable on PATH (a dependency-free `which`), returning its full
+    # path or nil. Overridable in specs so shooter resolution is testable.
+    def which(cmd)
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+        candidate = File.join(dir, cmd)
+        return candidate if File.executable?(candidate) && !File.directory?(candidate)
+      end
+      nil
+    end
+  end
+end

data/lib/docs_kit/seo_config.rb ADDED Viewed

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+module DocsKit
+  # The per-site SEO / social-share knobs, read by DocsUI::MetaTags to emit the
+  # <head> meta/link tags (description, Open Graph, Twitter Card, canonical,
+  # favicon, theme-color). Nested under DocsKit::Configuration#seo so a site
+  # configures it as a small block:
+  #
+  #   DocsKit.configure do |c|
+  #     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_site = "@my_handle"
+  #   end
+  #
+  # Every field defaults to a backwards-safe value: a site that sets none still
+  # renders a valid minimal Open Graph block and no broken empty tags. Plain
+  # accessors (not Data.define) because each field is individually assignable in
+  # the `c.seo.x = ...` block, mirroring DocsKit::Configuration's own style.
+  class SeoConfig
+    # A one-line page/site description → <meta name="description"> and
+    # og:description / twitter:description. nil omits the description tags
+    # (DocsUI::Page derives a per-page value from #lead when a page sets none).
+    attr_accessor :description
+    # 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
+    # (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.
+    # Both nil by default (a site with no X presence emits neither tag).
+    attr_accessor :twitter_site, :twitter_creator
+    # The og:locale (e.g. "en_US", "sv_SE").
+    attr_accessor :locale
+    # The site's canonical base URL (e.g. "https://docs.example.com"). When set,
+    # og:image/og:url/canonical are absolutized against it even off a request
+    # (a static build, an isolated render). nil → DocsUI::MetaTags falls back to
+    # the request base URL, and omits canonical/absolute og:url when there's no
+    # request either.
+    attr_accessor :site_url
+    # A robots directive (e.g. "noindex, nofollow") → <meta name="robots">. nil
+    # omits the tag, so the page is indexable by default.
+    attr_accessor :favicon
+    # A favicon asset path/URL → <link rel="icon">. nil omits the link (the host
+    # may serve /favicon.ico itself).
+    attr_accessor :robots
+    # A theme-color (e.g. "#0f172a") → <meta name="theme-color">, tinting mobile
+    # browser chrome. nil omits the tag.
+    attr_accessor :theme_color
+    def initialize
+      @description     = nil
+      @og_image        = nil
+      @og_type         = "website"
+      @twitter_card    = "summary_large_image"
+      @twitter_site    = nil
+      @twitter_creator = nil
+      @locale          = "en_US"
+      @site_url        = nil
+      @robots          = nil
+      @favicon         = nil
+      @theme_color     = nil
+    end
+  end
+end

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

@@ -169,6 +169,9 @@ after_bundle do
     Next:
       cd #{app_name}
       bin/dev                     # or bin/rails server
+      bin/rails docs_kit:og       # generate your social-share image from the landing page
+                                  # (needs a headless browser: shot-scraper or chromium)
+    SEO: set c.seo.* in config/initializers/docs_kit.rb (description, og_image, twitter_site).
     Deploy: push, create a GitHub Release (or run the Deploy docs workflow).
       Set repo secrets: SSH_PRIVATE_KEY, DEPLOY_HOST, DEPLOY_DOMAIN (env: docs).
   MSG

data/lib/docs_kit/version.rb CHANGED Viewed

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

data/lib/docs_kit.rb CHANGED Viewed

@@ -54,6 +54,13 @@ loader.push_dir(File.expand_path("docs_kit", __dir__), namespace: DocsKit)
 loader.push_dir(File.expand_path("../app/components/docs_ui", __dir__), namespace: DocsUI)
 loader.ignore(File.expand_path("docs_kit/version.rb", __dir__))
 loader.ignore(File.expand_path("docs_kit/configuration.rb", __dir__))
+# Required eagerly by configuration.rb (a plain-Ruby value object, no Rails), so
+# ignore it here too or zeitwerk double-manages the constant.
+loader.ignore(File.expand_path("docs_kit/seo_config.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.
+loader.ignore(File.expand_path("docs_kit/og_generator.rb", __dir__))
 # docs_kit/rubocop.rb is the RuboCop-cop entry point: it defines cops under
 # RuboCop::Cop::DocsKit::*, not a DocsKit::Rubocop constant, so zeitwerk must not
 # manage it. It (and the cops under lib/rubocop/, which are outside the loader's

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

@@ -168,6 +168,16 @@ module DocsKit
         create_file "app/assets/builds/.keep", ""
       end
+      # 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"
+      end
       def wire_assets_and_package_json
         # Serve the bun-built CSS from app/assets/builds.
         inject_into_file "config/initializers/assets.rb",

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

@@ -30,6 +30,28 @@ Rails.application.config.to_prepare do
     #   # { href: "https://discord.gg/INVITE",   label: "Discord", icon: :discord },
     # ]
+    # SEO + social sharing. docs-kit emits a full <head> (description, Open Graph,
+    # Twitter Card, canonical, favicon, theme-color) from these knobs — a shared
+    # link renders a rich card with zero markup. Every field is optional; a site
+    # 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.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"  # 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
+    #
+    # 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
     # theme's CSS is scoped under [data-theme=X] for each shipped dark theme, so

data/lib/generators/docs_kit/install/templates/docs_kit_og.rake ADDED Viewed

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+# Generate this site's social-share (Open Graph / Twitter) images by
+# screenshotting its OWN landing page, so a shared link renders a real card of
+# your docs — not the neutral placeholder docs-kit ships. Run it whenever the
+# landing page changes materially:
+#
+#   bin/rails docs_kit:og
+#
+# It boots the app, serves it locally, screenshots "/" at the standard sizes, and
+# writes them into app/assets/images/og/. Point c.seo.og_image at the result
+# (the default "og/og.png" already matches). This is a documented, manual routine
+# (like phlex-reactive's vendored-client re-sync) — never run automatically, so a
+# machine without a headless browser is never blocked at deploy time.
+#
+# It shells out to a headless-browser CLI you already have; it is NOT a docs-kit
+# runtime dependency. Supported (auto-detected, first one found wins), override
+# with DOCS_KIT_SHOT:
+#   * shot-scraper   (https://shot-scraper.datasette.io) — `pipx install shot-scraper`
+#   * chromium/chrome headless --screenshot
+# Set DOCS_KIT_OG_URL to shoot a deployed URL instead of booting locally.
+namespace :docs_kit do
+  desc "Screenshot the landing page into app/assets/images/og/{og,twitter,square}.png"
+  task og: :environment do
+    require "docs_kit/og_generator"
+    sizes = {
+      "og.png" => [1200, 630],       # Open Graph / twitter summary_large_image
+      "twitter.png" => [1024, 512],  # Twitter summary card
+      "square.png" => [600, 600]     # square fallback (some chat clients)
+    }
+    out_dir = Rails.root.join("app/assets/images/og")
+    DocsKit::OgGenerator.new(
+      url: ENV.fetch("DOCS_KIT_OG_URL", nil),
+      out_dir: out_dir,
+      sizes: sizes,
+      shooter: ENV.fetch("DOCS_KIT_SHOT", nil)
+    ).call
+    puts "✅ Wrote #{sizes.keys.join(', ')} to #{out_dir.to_s.sub("#{Dir.pwd}/", '')}"
+    puts "   Point c.seo.og_image at one of them (default \"og/og.png\" already does)."
+  end
+end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -176,6 +176,7 @@ files:
 - app/components/docs_ui/json_response.rb
 - app/components/docs_ui/markdown.rb
 - app/components/docs_ui/markdown_action.rb
+- app/components/docs_ui/meta_tags.rb
 - app/components/docs_ui/on_this_page.rb
 - app/components/docs_ui/open_api_operation.rb
 - app/components/docs_ui/page.rb
@@ -214,6 +215,7 @@ files:
 - lib/docs_kit/mcp_server.rb
 - lib/docs_kit/mcp_tools.rb
 - lib/docs_kit/nav_item.rb
+- lib/docs_kit/og_generator.rb
 - lib/docs_kit/open_api.rb
 - lib/docs_kit/open_api/document.rb
 - lib/docs_kit/open_api/operation.rb
@@ -223,6 +225,7 @@ files:
 - 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/templates/new_site.rb
 - lib/docs_kit/topbar_link.rb
@@ -237,6 +240,7 @@ files:
 - lib/generators/docs_kit/install/templates/doc.rb.erb
 - 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
 - lib/generators/docs_kit/install/templates/installation_page.rb.erb
 - lib/generators/docs_kit/install/templates/landing.rb.erb
 - lib/generators/docs_kit/install/templates/landings_controller.rb.erb