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

docs-kit 1.0.1 → 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 (11) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +21 -8
data/README.md +17 -10
data/app/components/docs_ui/meta_tags.rb +33 -30
data/lib/docs_kit/seo_config.rb +9 -7
data/lib/docs_kit/version.rb +1 -1
data/lib/generators/docs_kit/install/install_generator.rb +6 -10
data/lib/generators/docs_kit/install/templates/docs_kit.rb.erb +6 -4
metadata +1 -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: df9e88e060d79197aaf8f9247000b31f5da3568bbf7099f18f59bc216b11e877
+  data.tar.gz: 1fde31a5d995087e06b62f2b58983e73acfc12309d6958db6e913f538894edbf
 SHA512:
-  metadata.gz: 6d6846fbbe1169e4513a2061b298a15ae65281da4eacaf3486d34392ceb52ecfcff7542df8eb28c2f8d5ff2c3b443c0e75a8371019b524293a51e76fbd964e80
-  data.tar.gz: ee32039817d7e32af7b6a97e2abb2bed4ff5142974fe8e2c43f40949755343e8d6c96781d82603b61fa4794f92f3c24ef78832d33be0288c32c39308dfea1a64
+  metadata.gz: 8c8de40c603fa96e5fbee8aa377816894566c3b4f40c632e51d1a1055b875fe48b3349ef9cc833f0bada6b85d3504cfdc433ef27c9cdb9fff16ce30e81f0aa16
+  data.tar.gz: 7230b76a2e9d68d98061c92b2002ad59a2ca9a4609df75d8de2c68f4d911c78938188e1b87d1ced4c3ad7ff52ea4e9e6105fe8b0d2f43c27da826b77297f82fb

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

@@ -180,9 +180,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 +199,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)

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/version.rb CHANGED Viewed

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

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

@@ -168,18 +168,14 @@ 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
       def wire_assets_and_package_json

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.2
 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

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>