RubyGems - docs-kit - Versions diffs - 1.0.4 → 1.0.6 - Mend

docs-kit 1.0.4 → 1.0.6

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

checksums.yaml +4 -4
data/CHANGELOG.md +20 -0
data/app/components/docs_ui/landing.rb +188 -0
data/lib/docs_kit/configuration.rb +10 -0
data/lib/docs_kit/landing_config.rb +160 -0
data/lib/docs_kit/version.rb +1 -1
data/lib/docs_kit.rb +1 -0
data/lib/generators/docs_kit/install/templates/docs_kit.rb.erb +22 -0
data/lib/generators/docs_kit/install/templates/landing.rb.erb +6 -15
metadata +3 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0df82a287c454b9eff2243210da5dca51eb8f218434ede180e1ffdb3be7c941
-  data.tar.gz: 215324e7604b6dacf964e736b6d29f38b30b4b047541ca5042dc1b1879132cae
+  metadata.gz: 51075e7a45365a86a3f97c35341cd2288ad35aba3f9ed1f4e31cea17edcacbfc
+  data.tar.gz: b5f49f3397f6b5d9090ee4560d82242a063a2cf8d0a7682c7a2fe7154364541f
 SHA512:
-  metadata.gz: 8fd44f0619a0f80d84ece5aff198252e4dd6bd74353d675ada893f585a8a335d456269a4ddcbe36a28c219687891f2058cfb7092748572dfb24ad7183a724931
-  data.tar.gz: d2229edb327e97156d7e6ebdc593bbcdb52e6a68a6c92734697ca2e5898729cf01b6f192c33be03c1b27f4339ecdae31521c8de8c7c145cc4f6d89c01bc9e037
+  metadata.gz: 6b725ba25e7919148f89c6511300a0998e2d6d9d9539d84fa4c845cc8b933a24ba08c79131de936872000c4b56d787e8eeab17f9e46e8fbbe1a03a8b9d6eabf5
+  data.tar.gz: 11c6600410734838f11aa53957ccfeb89808996511e4b377e41b23e2d6f6afc23cee5cf161a44e12bb61c48e194843b09ed4550d4c341403b2806804f05bdf1e

data/CHANGELOG.md CHANGED Viewed

@@ -18,6 +18,26 @@
 ### Added
+- **`DocsUI::Landing` hero logo (`c.landing.logo`).** The landing hero now takes
+  an optional brand mark above the eyebrow, in two forms: an inline single-path
+  SVG (`{ svg: "<path d>", viewbox:, label: }`, rendered with `fill: currentColor`
+  so it adapts to the theme) or an image (`{ src:, alt: }`, resolved through the
+  site's asset pipeline). nil (the default) omits it, so it's backwards-compatible.
+  This closes the gap a mounted docs app hit — a hero with no way to show the
+  product's own logo — the first consumer to try `DocsUI::Landing` on a real site.
+- **`DocsUI::Landing` — a config-driven marketing landing page.** Every consuming
+  site (and this dogfood site) was hand-rolling a home page; now render
+  `DocsUI::Landing` and drive it from a new `c.landing` config block
+  (`DocsKit::LandingConfig`): a hero (`eyebrow`, `title` — wrap a run in
+  `**double asterisks**` to accent it in the primary color, `lead`, an optional
+  `install` code snippet, and `ctas`), a `features` card grid, and a
+  registry-grouped documentation index built from `nav_groups` (so it never drifts
+  from the authored pages). Every field is optional — with an empty `c.landing` it
+  still renders a minimal hero (brand + doc index), never a broken page — and its
+  `.md`/`.text` twin works like any page. The install generator's `landings#show`
+  now renders it and the initializer documents `c.landing`. This is the first
+  landing pattern proven on a **mounted** docs app (a docs section inside a larger
+  Rails app whose `/` is already taken), contributed back from that use case.
 - **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

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+module DocsUI
+  # The marketing landing page — a hero (an optional brand logo + eyebrow + title +
+  # lead + optional install snippet + CTA buttons), a feature-card grid, and a
+  # registry-grouped documentation index — rendered inside DocsUI::Shell. Every
+  # consuming site was hand-rolling this; drive it from config instead:
+  #
+  #   # config/initializers/docs_kit.rb
+  #   DocsKit.configure do |c|
+  #     c.landing.logo     = { svg: "M4 2h9l5 5…Z", viewbox: "0 0 22 24", label: "Acme" }
+  #     c.landing.eyebrow  = "Developer Docs"
+  #     c.landing.title    = "Jobs & events on **Postgres**"   # ** ** → primary color
+  #     c.landing.lead     = "PostgreSQL-native jobs + event bus for Rails."
+  #     c.landing.install  = { code: 'gem "pgbus"', filename: "Gemfile", lexer: :ruby }
+  #     c.landing.ctas     = [{ label: "Get started", href: "/docs/overview", style: :primary }]
+  #     c.landing.features = [{ icon: "database", title: "One database", body: "No Redis." }]
+  #   end
+  #
+  #   # a controller that includes DocsKit::Controller
+  #   def show = render_page(DocsUI::Landing.new)
+  #
+  # Everything is optional: with an empty c.landing it still renders a minimal hero
+  # (the brand name + the doc index), never a broken page. The doc index is built
+  # from DocsKit.configuration.nav_groups — the same registry the sidebar uses — so
+  # it never drifts from the authored pages.
+  #
+  # It IS a full document (composes Shell), so a controller renders it with
+  # `layout: false`, exactly like DocsUI::Page (DocsKit::Controller#render_page
+  # does this). The `.md`/`.text` twin of the landing works too — MarkdownExport
+  # walks the same #docs-content region Shell stamps.
+  class Landing < Phlex::HTML
+    include Phlex::Rails::Helpers::Request
+    # For the image-form hero logo (c.landing.logo = { src: … }): resolve the asset
+    # path through the site's pipeline to its digested /assets URL.
+    include Phlex::Rails::Helpers::ImageURL
+    def view_template
+      render DocsUI::Shell.new(title: landing.eyebrow || config.brand) do
+        div(class: "mx-auto max-w-5xl") do
+          hero
+          feature_grid
+          doc_index
+        end
+      end
+    end
+    private
+    def config = DocsKit.configuration
+    def landing = config.landing
+    # --- hero ----------------------------------------------------------------
+    def hero
+      div(class: "flex flex-col gap-6") do
+        logo
+        eyebrow
+        heading
+        lead
+        install_snippet
+        ctas
+      end
+    end
+    # The brand mark — an inline single-path SVG (currentColor, theme-adaptive) or
+    # an <img>. Rendered above the eyebrow, like a product wordmark.
+    def logo
+      return unless (mark = landing.hero_logo)
+      if mark.inline?
+        svg(viewbox: mark.viewbox, class: "h-9 w-auto text-primary", fill: "currentColor",
+            role: "img", aria_label: mark.label) do |s|
+          s.title { mark.label } if mark.label
+          s.path(d: mark.svg)
+        end
+      else
+        img(src: image_url(mark.src), alt: mark.alt.to_s, class: "h-9 w-auto")
+      end
+    end
+    def eyebrow
+      return unless (text = landing.eyebrow)
+      p(class: "text-sm font-medium uppercase tracking-wide text-primary") { text }
+    end
+    # The <h1>. A **run** wrapped in double asterisks renders in the primary color
+    # (the one bit of markdown we honor, so a site can accent a word without HTML).
+    def heading
+      h1(class: "text-4xl font-bold tracking-tight md:text-5xl") do
+        (landing.title || config.brand).to_s.split(/\*\*(.+?)\*\*/).each_with_index do |part, index|
+          next if part.empty?
+          index.odd? ? span(class: "text-primary") { part } : plain(part)
+        end
+      end
+    end
+    def lead
+      return unless (text = landing.lead || config.tagline)
+      p(class: "max-w-2xl text-lg text-base-content/70") { text }
+    end
+    def install_snippet
+      return unless (snippet = landing.install_snippet)
+      render DocsUI::Code.new(snippet[:code], lexer: snippet[:lexer], filename: snippet[:filename])
+    end
+    def ctas
+      buttons = landing.ctas
+      return if buttons.empty?
+      div(class: "flex flex-wrap items-center gap-4 pt-2") do
+        buttons.each { |cta| cta_button(cta) }
+      end
+    end
+    def cta_button(cta)
+      attrs = { href: cta.href, class: "#{cta.btn_class} gap-2" }
+      if cta.external?
+        attrs[:target] = "_blank"
+        attrs[:rel] = "noopener"
+      end
+      a(**attrs) do
+        render DocsUI::BrandMark.new(cta.icon, class: "size-4", label: cta.label) if cta.icon
+        plain cta.label
+      end
+    end
+    # --- feature grid --------------------------------------------------------
+    def feature_grid
+      features = landing.features
+      return if features.empty?
+      div(class: "mt-12 grid gap-4 sm:grid-cols-2") do
+        features.each { |feature| feature_card(feature) }
+      end
+    end
+    def feature_card(feature)
+      div(class: "rounded-box border border-base-300 bg-base-200/40 p-5") do
+        div(class: "flex items-center gap-2 text-primary") do
+          render DocsUI::Icon.new(feature.icon, class: "size-5") if feature.icon
+          span(class: "font-semibold text-base-content") { feature.title }
+        end
+        p(class: "mt-2 text-sm text-base-content/70") { feature.body } if feature.body
+      end
+    end
+    # --- documentation index -------------------------------------------------
+    # The registry-grouped page index. nav_groups is the three-level Hash the
+    # sidebar renders ({ heading => { subgroup => [NavItem] } }); the landing
+    # flattens each heading's items into a linked column.
+    def doc_index
+      return if !landing.doc_index? || (groups = flattened_nav).empty?
+      div(class: "mt-16") do
+        h2(class: "text-sm font-semibold uppercase tracking-wide text-base-content/50") { "Documentation" }
+        div(class: "mt-6 grid gap-8 sm:grid-cols-2") do
+          groups.each { |heading, items| doc_index_group(heading, items) }
+        end
+      end
+    end
+    def doc_index_group(heading, items)
+      div do
+        h3(class: "text-xs font-semibold uppercase tracking-wide text-base-content/40") { heading }
+        ul(class: "mt-3 flex flex-col gap-2") do
+          items.each { |item| li { a(href: item.href, class: "link link-hover text-sm") { item.label } } }
+        end
+      end
+    end
+    # Collapse nav_groups ({ heading => { subgroup => [item] } }) to
+    # { heading => [item, ...] } — the landing shows one flat column per heading.
+    def flattened_nav
+      config.nav_groups.each_with_object({}) do |(heading, grouped), acc|
+        items = Array(grouped).flat_map { |_subgroup, list| Array(list) }
+        acc[heading] = items unless items.empty?
+      end
+    end
+  end
+end

data/lib/docs_kit/configuration.rb CHANGED Viewed

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require_relative "seo_config"
+require_relative "landing_config"
 module DocsKit
   # Per-site configuration for the shared docs chrome. Everything that differs
@@ -281,6 +282,15 @@ module DocsKit
       @seo ||= DocsKit::SeoConfig.new
     end
+    # The landing-page knobs (DocsKit::LandingConfig), read by DocsUI::Landing.
+    # Lazily built and memoized so a `c.landing.title = ...` block mutates the one
+    # instance the component later reads. A site that never touches it still gets a
+    # minimal hero + the doc index (see LandingConfig), so DocsUI::Landing is safe
+    # to render with zero landing config.
+    def landing
+      @landing ||= DocsKit::LandingConfig.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/landing_config.rb ADDED Viewed

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+module DocsKit
+  # The per-site landing-page knobs, read by DocsUI::Landing to render a marketing
+  # home page (hero + feature grid + doc index) without a site hand-rolling one.
+  # Nested under DocsKit::Configuration#landing so a site configures it as a block:
+  #
+  #   DocsKit.configure do |c|
+  #     c.landing.eyebrow = "Developer Docs"
+  #     c.landing.title   = "Jobs & events on Postgres"   # highlight a run with **…**
+  #     c.landing.lead    = "PostgreSQL-native job processing and event bus for Rails."
+  #     c.landing.install = { code: 'gem "pgbus"', filename: "Gemfile", lexer: :ruby }
+  #     c.landing.ctas = [
+  #       { label: "Get started", href: "/docs/overview", style: :primary },
+  #       { label: "GitHub",      href: "https://github.com/me/repo", style: :ghost, icon: :github },
+  #     ]
+  #     c.landing.features = [
+  #       { icon: "database", title: "One database", body: "No Redis, no broker." },
+  #       { icon: "zap",      title: "Fast",         body: "…" },
+  #     ]
+  #   end
+  #
+  # Every field is optional and defaults to a backwards-safe value: a site that
+  # sets none still renders a minimal hero (the brand + a doc index), never a
+  # broken page. Plain accessors (not Data.define) because each field is
+  # individually assignable in the `c.landing.x = ...` block, mirroring
+  # DocsKit::SeoConfig.
+  class LandingConfig
+    # An optional brand logo/mark rendered at the top of the hero (above the
+    # eyebrow), like a product wordmark. A Hash in one of two forms:
+    #   { svg: "<path d …>", viewbox: "0 0 81 45", label: "Brand" }  # inline mark
+    #   { src: "logo.svg", alt: "Brand" }                            # image asset/URL
+    # The inline `svg` form renders with `fill: currentColor` so it adapts to the
+    # theme (light/dark) — best for a single-color mark. nil omits the logo.
+    # See #hero_logo (the normalized Logo value object) and DocsUI::Landing.
+    attr_writer :logo
+    # A small uppercase kicker above the title (e.g. "Developer Docs"). nil omits it.
+    attr_accessor :eyebrow
+    # The hero <h1>. Wrap a run in **double asterisks** to render it in the primary
+    # color (e.g. "Jobs & events on **Postgres**"). nil falls back to the brand.
+    attr_accessor :title
+    # The muted lead paragraph under the title. nil falls back to the tagline.
+    attr_accessor :lead
+    # An optional install/quickstart code block shown in the hero, as a Hash:
+    #   { code: "gem \"x\"", filename: "Gemfile", lexer: :ruby }
+    # nil omits the block. See #install_snippet for the normalized form.
+    attr_accessor :install
+    # Whether to render the registry-grouped documentation index below the hero
+    # (the "Documentation" section linking every authored page). Default true.
+    attr_writer :doc_index
+    # The hero call-to-action buttons, each a Hash normalized into a Cta:
+    #   { label:, href:, style: :primary|:ghost (default :ghost), icon: (brand/lucide token) }
+    attr_writer :ctas
+    # The feature cards shown in a grid under the hero, each a Hash normalized into
+    # a Feature: { icon: (lucide name), title:, body: }.
+    attr_writer :features
+    def initialize
+      @doc_index = true
+      @ctas = []
+      @features = []
+    end
+    # Whether the doc index is shown (default true).
+    def doc_index? = @doc_index != false
+    # The CTAs as normalized Cta value objects (empty when unset).
+    def ctas
+      Array(@ctas).map { |cta| Cta.from(cta) }
+    end
+    # The features as normalized Feature value objects (empty when unset).
+    def features
+      Array(@features).map { |feature| Feature.from(feature) }
+    end
+    # The install block normalized to { code:, filename:, lexer: } with a sensible
+    # default lexer, or nil when unset.
+    def install_snippet
+      return if @install.nil?
+      attrs = @install.to_h.transform_keys(&:to_sym)
+      { code: attrs[:code].to_s, filename: attrs[:filename], lexer: (attrs[:lexer] || :shell).to_sym }
+    end
+    # The hero logo as a normalized Logo value object, or nil when unset.
+    def hero_logo
+      return if @logo.nil?
+      Logo.from(@logo)
+    end
+    # One hero call-to-action button. `style` maps to a daisyUI btn variant
+    # (:primary → btn-primary, anything else → btn-ghost). `icon` is an optional
+    # brand/lucide token rendered before the label (DocsUI::BrandMark resolves it).
+    Cta = Data.define(:label, :href, :style, :icon) do
+      def initialize(label:, href:, style: :ghost, icon: nil)
+        super(label:, href:, style: style&.to_sym, icon: icon)
+      end
+      def self.from(cta)
+        return cta if cta.is_a?(self)
+        attrs = cta.to_h.transform_keys(&:to_sym)
+        new(label: attrs[:label], href: attrs[:href], style: attrs[:style] || :ghost, icon: attrs[:icon])
+      end
+      # The daisyUI button class for this CTA's style.
+      def btn_class = style == :primary ? "btn btn-primary" : "btn btn-ghost"
+      # Whether the href points off-site (absolute http/https) — the component adds
+      # target=_blank + rel=noopener only for external links.
+      def external? = href.to_s.match?(%r{\Ahttps?://}i)
+    end
+    # One feature card: a lucide icon name, a title, and a short body.
+    Feature = Data.define(:icon, :title, :body) do
+      def initialize(title:, icon: nil, body: nil)
+        super
+      end
+      def self.from(feature)
+        return feature if feature.is_a?(self)
+        attrs = feature.to_h.transform_keys(&:to_sym)
+        new(icon: attrs[:icon], title: attrs[:title], body: attrs[:body])
+      end
+    end
+    # The hero brand logo — either an inline single-path SVG mark (`svg` = the
+    # `<path d>` data, `viewbox` = its viewBox) rendered with fill: currentColor so
+    # it adapts to the theme, OR an image (`src` = an asset path/URL, `alt` = its
+    # accessible name). `label` is the accessible name for the inline mark.
+    Logo = Data.define(:svg, :viewbox, :src, :alt, :label) do
+      def initialize(svg: nil, viewbox: "0 0 24 24", src: nil, alt: nil, label: nil)
+        super
+      end
+      def self.from(logo)
+        return logo if logo.is_a?(self)
+        attrs = logo.to_h.transform_keys(&:to_sym)
+        new(
+          svg: attrs[:svg], viewbox: attrs[:viewbox] || "0 0 24 24",
+          src: attrs[:src], alt: attrs[:alt], label: attrs[:label]
+        )
+      end
+      # An inline SVG mark (vs. an <img>). True when `svg` path data is present.
+      def inline? = !svg.to_s.empty?
+    end
+  end
+end

data/lib/docs_kit/version.rb CHANGED Viewed

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

data/lib/docs_kit.rb CHANGED Viewed

@@ -57,6 +57,7 @@ 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__))
+loader.ignore(File.expand_path("docs_kit/landing_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.

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

@@ -104,6 +104,28 @@ Rails.application.config.to_prepare do
     # then. README → "Add your docs to an agent (MCP)".
     # c.mcp = false
+    # The landing page (app/views/landings/show.rb renders DocsUI::Landing) — a
+    # marketing hero + feature grid + a registry-grouped doc index, all from these
+    # knobs. Every field is optional; with none set it still renders a minimal hero
+    # (the brand + the doc index). Wrap a run in **double asterisks** to accent it
+    # in the primary color.
+    # c.landing.logo = { svg: "M4 2h9l5 5…Z", viewbox: "0 0 22 24", label: "<%= app_brand %>" }
+    #   # ^ an inline single-path SVG mark (fill: currentColor, theme-adaptive), OR
+    #   #   an image: { src: "logo.svg", alt: "<%= app_brand %>" }
+    # c.landing.eyebrow = "Developer Docs"
+    # c.landing.title   = "The <%= app_brand %> **API**"
+    # c.landing.lead    = "One sentence on what your product does."
+    # c.landing.install = { code: 'gem "<%= app_brand.downcase %>"', filename: "Gemfile", lexer: :ruby }
+    # c.landing.ctas = [
+    #   { label: "Get started", href: "/docs/overview", style: :primary },
+    #   { label: "GitHub", href: "https://github.com/OWNER/REPO", style: :ghost, icon: :github },
+    # ]
+    # c.landing.features = [
+    #   { icon: "zap",      title: "Fast",         body: "Why it's fast." },
+    #   { icon: "database", title: "One database", body: "No extra moving parts." },
+    # ]
+    # c.landing.doc_index = false   # hide the "Documentation" index section
     # The sidebar nav derives from the registry — one heading → one registry.
     # Each registry's authored pages become NavItems automatically (an unwritten
     # page is skipped, so no dead links). For bespoke nav (interleaved

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

@@ -2,23 +2,14 @@
 module Views
   module Landings
-    # The home page. Renders inside DocsUI::Shell (the full document + drawer
-    # shell); links to the authored docs.
+    # The home page — a marketing hero + feature grid + doc index, rendered by the
+    # shared DocsUI::Landing component. Customize it entirely from config:
+    # `c.landing.{eyebrow, title, lead, install, ctas, features}` in
+    # config/initializers/docs_kit.rb. With no landing config it still renders a
+    # minimal hero (the brand + the doc index), so this works out of the box.
     class Show < Phlex::HTML
-      include Phlex::Rails::Helpers::Routes
       def view_template
-        render DocsUI::Shell.new do
-          div(class: "prose max-w-none") do
-            h1 { "<%= app_brand %>" }
-            p { "Documentation, built with docs-kit." }
-            ul do
-              Doc.all.select(&:view_class).each do |doc|
-                li { a(href: "/docs/#{doc.slug}", class: "link") { doc.title } }
-              end
-            end
-          end
-        end
+        render DocsUI::Landing.new
       end
     end
   end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.6
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -174,6 +174,7 @@ files:
 - app/components/docs_ui/header.rb
 - app/components/docs_ui/icon.rb
 - app/components/docs_ui/json_response.rb
+- app/components/docs_ui/landing.rb
 - app/components/docs_ui/markdown.rb
 - app/components/docs_ui/markdown_action.rb
 - app/components/docs_ui/meta_tags.rb
@@ -207,6 +208,7 @@ files:
 - lib/docs_kit/configuration.rb
 - lib/docs_kit/controller.rb
 - lib/docs_kit/engine.rb
+- lib/docs_kit/landing_config.rb
 - lib/docs_kit/llms_text.rb
 - lib/docs_kit/markdown_export.rb
 - lib/docs_kit/markdown_export/blocks.rb