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

docs-kit 0.1.0 → 1.0.1

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

checksums.yaml +4 -4
data/CHANGELOG.md +12 -0
data/README.md +44 -0
data/app/assets/images/og/og.png +0 -0
data/app/assets/images/og/og.svg +1 -0
data/app/components/docs_ui/meta_tags.rb +163 -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 +79 -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 +14 -0
data/lib/generators/docs_kit/install/templates/docs_kit.rb.erb +20 -0
data/lib/generators/docs_kit/install/templates/docs_kit_og.rake +44 -0
metadata +32 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa6ab8345eda1cc169927e190d267236133574627f0075f528bb417d842b2868
-  data.tar.gz: f620e9eb3e6bdca64e1d8365ad5cb2647bcc38d8576af8f2f7e2a1b397f8584c
+  metadata.gz: 72b8c93e9a6c2896bb31bd9ba8aaaf8cf5692424ab84d92ca8e5817d1b85291c
+  data.tar.gz: bfc8a48ab90cbb0d62083f864fd8f188a645070b86bf4af1ff63c9a302160e99
 SHA512:
-  metadata.gz: b813b8eef499c093632c7b06974acdf3b5bd7033235020b815c19933ffb8ba82d08f7640791c5cb3685334ca67fa7e93012a83b214308339495ddabdbd4edaa8
-  data.tar.gz: ad7d05a4a84edc6cf1a4348c3e04da3f01a7402be4a0d55d68cdbad1978b5735eec30846edf8994b6b6747dac452a03ca4f5c7eec583f359935a847f136c5cfe
+  metadata.gz: 6d6846fbbe1169e4513a2061b298a15ae65281da4eacaf3486d34392ceb52ecfcff7542df8eb28c2f8d5ff2c3b443c0e75a8371019b524293a51e76fbd964e80
+  data.tar.gz: ee32039817d7e32af7b6a97e2abb2bed4ff5142974fe8e2c43f40949755343e8d6c96781d82603b61fa4794f92f3c24ef78832d33be0288c32c39308dfea1a64

data/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,18 @@
 ### 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)
 - 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,50 @@ 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"            # generated by `bin/rails docs_kit:og`
+c.seo.twitter_site = "@your_handle"
+c.seo.site_url     = "https://docs.example.com"  # absolutizes og:image + canonical
+# 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.** 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:
+```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.
 ### Custom nav (advanced)
 Sites that interleave several registries under a heading, or need custom

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

Binary file

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

@@ -0,0 +1 @@

+ <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>

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

@@ -0,0 +1,163 @@
+# 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. 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).
+  class MetaTags < Phlex::HTML
+    include Phlex::Rails::Helpers::Request
+    # 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-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.
+    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
+    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
+    # 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,
+    # 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,79 @@
+# 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, 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`.
+    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.
+    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        = "og/og.png"
+      @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 = "0.1.0"
+  VERSION = "1.0.1"
 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,20 @@ 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.
+      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
       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,26 @@ 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.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.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:
+    #   bin/rails docs_kit:og
     # 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: 0.1.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -16,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: phlex-rails
   requirement: !ruby/object:Gem::Requirement
@@ -64,6 +70,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -71,6 +80,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: commonmarker
   requirement: !ruby/object:Gem::Requirement
@@ -92,6 +104,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -99,6 +114,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -120,6 +138,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.75'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -127,6 +148,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.75'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 description: DocsKit is a reusable documentation-site component library for Phlex
   + daisyUI. It extracts the shared shell, sidebar, code blocks, and page kit so multiple
   docs sites look identical and are maintained in one place. Reactive demos (phlex-reactive)
@@ -140,6 +164,8 @@ 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
@@ -152,6 +178,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
@@ -190,6 +217,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
@@ -199,6 +227,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
@@ -213,6 +242,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
@@ -246,7 +276,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.9
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Shared Phlex docs-site chrome (shell, sidebar, code, theme switcher) built
   on daisyUI