docs-kit 1.0.5 → 1.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf583f1cfdfc22d788c0dcffac91b35a374138d8670cfe24bdef3cc2e05eb171
-  data.tar.gz: 7c3168bcaf1d0d1939350d704a12cb39f0e37a561be75a255517dcf82e531eba
+  metadata.gz: fa41c41824768d1db2a5ad5a7ba9b983b0f81032c8b5a3f80277e2611e203449
+  data.tar.gz: 60cd31b54d83c9c6920ff48d27ec177f81b7a240fdf513e65f9617837cc6c738
 SHA512:
-  metadata.gz: 43c6f2f94b23ca4ad589a701f92121b3dcc3027cc06173432a653e215e9c4da2ab62e1a2044cf9ef3b1e19be9516d7a2698fc6b259f390ce3a15e5c2df50f6eb
-  data.tar.gz: 001253000ff36f16cd9ab76377cb4175dcab526a5a8dc2897fd0bde9809016d0dbd42fe5aa1e6474c24e7260eed25468843c393a4e73d447dc01f16c1a87b489
+  metadata.gz: e23f649705ac6216e4961c389eab64965961023123937364e4915b608264bf994ec0885c1958929884449d4eb4f6d9202ed6a5fa7fb9dd373c6a2202e8850ea1
+  data.tar.gz: 0a047f0b8b45fdce21b9121b13461a5c003ec307586ef4b49bbb3ead0c4d79f44db00a243eda7792fc5be173f3b135195efad4212360527cb2ef5e143eafd5e5

data/CHANGELOG.md

@@ -18,6 +18,13 @@
 
 ### 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

data/README.md

@@ -81,6 +81,31 @@ site-owned content (your `Doc` registry, your pages, your themed
 `application.tailwind.css`). Drop `--sync` to also (re)scaffold missing content
 files — Thor prompts before overwriting anything that exists.
 
+### Version-aware migrations
+
+Every install and `--sync` stamps the docs-kit version it ran into your config
+initializer, as an inert comment on the first line:
+
+```ruby
+# docs-kit synced: v1.0.5
+# frozen_string_literal: true
+Rails.application.config.to_prepare do
+  DocsKit.configure do |c|
+    # ...
+```
+
+On the next `--sync` after a `bundle update docs-kit`, the generator reads that
+stamp, works out the gap to the newly-installed version, and runs the **ordered
+release-to-release migrations** in between — renamed config knobs, changed route
+shapes, restructured templates — in sequence, then restamps to the new version.
+A site created before the stamp existed (no comment) is treated as the earliest
+version, so it gets every migration. Migrations are **warn-only-safe** exactly
+like the drift report: what a step can't safely automate it prints as a manual
+checklist (`migration steps to apply by hand:`), never a destructive rewrite of
+a line you've edited. There are no migrations to apply yet — the mechanism ships
+ahead of the first release that needs one, so the upgrade path is already in
+place.
+
 ### One-time cleanup for sites created before these landed
 
 `--sync` detects drift it can't safely automate and prints a checklist — it
@@ -132,11 +157,15 @@ diff Dockerfile "$(bundle show docs-kit)/lib/generators/docs_kit/install/templat
 # config/initializers/docs_kit.rb
 DocsKit.configure do |c|
   c.brand        = "phlex-reactive"
-  c.brand_href   = "/docs"                                  # brand link target (default "/")
+  c.brand_href   = "/docs"                                  # the DOCS home: brand, sidebar, and "← Docs home" masthead link (default "/")
   c.title_suffix = "phlex-reactive"
   c.themes       = %w[dark light synthwave retro cyberpunk dracula night nord sunset]
   c.version_badge = -> { "v#{Phlex::Reactive::VERSION}" }   # optional
 
+  # Docs embedded in a bigger app? The way BACK to it — a labeled link rendered
+  # once in the topbar, right after the brand. Unset (default) renders nothing.
+  c.app_link = { href: "/", label: "Back to the app" }
+
   # Repo/social links in the topbar (next to the theme switcher).
   c.topbar_links = [
     { href: "https://github.com/you/phlex-reactive", label: "GitHub", icon: :github },
@@ -156,13 +185,15 @@ registry maps a heading to its authored pages (`Doc.nav_items`); a page that
 isn't written yet is skipped, so there are no dead links. Register a page with
 one line (see [Add a page](#add-a-page)) and it appears in the sidebar.
 
-### Brand link and dark code themes
+### The two homes, the brand link, and dark code themes
 
-Three knobs cover what sites used to shim by subclassing `DocsUI::Shell`:
+These knobs cover what sites used to shim by subclassing `DocsUI::Shell` or
+overriding route helpers:
 
 | Knob | Default | What it does |
 |------|---------|--------------|
-| `c.brand_href` | `"/"` | The href of the topbar brand link. Set it (e.g. `"/docs"`) instead of subclassing `Shell` to copy-paste `#topbar`. |
+| `c.brand_href` | `"/"` | The **docs home** — the href of the topbar brand, the sidebar brand, and each page's "← Docs home" masthead link. Set it (e.g. `"/docs"`) when the docs live under a subpath, instead of subclassing `Shell` or overriding `root_path`. |
+| `c.app_link` | `nil` | The **app home** — an opt-in `{ href:, label: }` link back to the application hosting the docs, rendered once in the topbar right after the brand (e.g. `{ href: "/", label: "Back to the app" }`). Unset renders nothing, so a standalone docs site is unchanged. External hrefs open in a new tab with `rel=noopener`. |
 | `c.code_theme_dark` | `nil` | A second Rouge theme for **dark** daisyUI themes. `nil` keeps the single-theme behavior (fully backwards compatible). When set, `DocsUI::Code` also emits this theme's CSS scoped under `[data-theme=X] .code-highlight` for each shipped dark theme, so code blocks stay readable when the switcher flips to a dark theme. |
 | `c.dark_themes` | daisyUI's built-in dark theme names | Which theme names count as dark for `code_theme_dark`. Intersected with `c.themes` at render time, so only shipped themes emit CSS. Override to name custom dark themes (e.g. `%w[zazu-dark]`). |
 

data/app/components/docs_ui/landing.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 module DocsUI
-  # The marketing landing page — a hero (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:
+  # 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."
@@ -30,6 +31,9 @@ module DocsUI
   # 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
@@ -50,6 +54,7 @@ module DocsUI
 
     def hero
       div(class: "flex flex-col gap-6") do
+        logo
         eyebrow
         heading
         lead
@@ -58,6 +63,22 @@ module DocsUI
       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)
 

data/app/components/docs_ui/page.rb

@@ -65,7 +65,7 @@ module DocsUI
         # "Markdown" action sits opposite "← Home"; it's chrome too, so it lives
         # inside the skipped nav and never appears in the .md twin.
         nav(class: "mb-6 flex items-center justify-between gap-4", data: { md_skip: true }) do
-          a(href: root_path, class: "link link-hover text-sm opacity-70") { "← Home" }
+          a(href: home_href, class: "link link-hover text-sm opacity-70") { "← Docs home" }
           render DocsUI::MarkdownAction.new(request.path) if markdown_action?
         end
 
@@ -92,5 +92,12 @@ module DocsUI
     def content
       raise NotImplementedError, "#{self.class} must implement #content"
     end
+
+    private
+
+    # The masthead "← Docs home" target: config.brand_href (the DOCS home, like
+    # the topbar/sidebar brand links) — never the host's root_path helper, which
+    # on an app-embedded site is the application root, not the docs landing.
+    def home_href = DocsKit.configuration.brand_href
   end
 end

data/app/components/docs_ui/shell.rb

@@ -157,6 +157,7 @@ module DocsUI
           label(for: DRAWER_ID, class: "btn btn-square btn-ghost btn-sm lg:hidden",
                 aria_label: "Open menu") { render DocsUI::Icon.new("menu", class: "size-5") }
           a(href: config.brand_href, class: "btn btn-ghost text-lg font-bold") { config.brand }
+          app_home_link
         end
         render DocsUI::SearchBox.new if config.search_enabled?
         div(class: "flex-none items-center") do
@@ -167,5 +168,22 @@ module DocsUI
         end
       end
     end
+
+    # The opt-in App Home link (config.app_link) — the way back to the hosting
+    # app, rendered once, right after the brand. Nothing renders when unset, so
+    # the topbar stays byte-identical for a site that never configures it.
+    # External hrefs open in a new tab with rel=noopener (same posture as
+    # DocsUI::TopbarLinks); a site-relative href opens in place.
+    def app_home_link
+      link = config.app_link
+      return unless link
+
+      a(
+        href: link.href,
+        class: "link link-hover text-sm opacity-70",
+        target: (link.external? ? "_blank" : nil),
+        rel: (link.external? ? "noopener noreferrer" : nil)
+      ) { link.label }
+    end
   end
 end

data/lib/docs_kit/configuration.rb

@@ -184,6 +184,15 @@ module DocsKit
     # Read the effective map via #api_clients (which merges), never @api_clients.
     attr_writer :api_clients
 
+    # The opt-in "App Home" link — the way back to the application that hosts
+    # the docs, rendered ONCE in the topbar right after the brand (e.g.
+    # "Back to the app" on a docs site embedded in a bigger app). A Hash
+    # ({ href:, label: }) or a DocsKit::TopbarLink; #app_link normalizes it.
+    # Defaults to nil → no link renders and the topbar is byte-identical to
+    # before. Distinct from #brand_href, which is the DOCS home (the brand,
+    # sidebar, and page-masthead links). Read via #app_link, never @app_link.
+    attr_writer :app_link
+
     # External links rendered in the topbar next to the theme switcher — a repo
     # link, a chat invite, a social profile. Each entry is a Hash
     # ({ href:, label:, icon: }) or a DocsKit::TopbarLink; #topbar_links
@@ -262,10 +271,19 @@ module DocsKit
       @api_base_url = "https://api.example.com"
       @api_auth_header = nil
       @api_clients = {}
+      @app_link = nil
       @topbar_links = []
       @openapi = nil
     end
 
+    # The normalized App Home link (a DocsKit::TopbarLink), or nil when unset —
+    # absent config, absent link, exactly like every other opt-in knob.
+    def app_link
+      return if @app_link.nil?
+
+      DocsKit::TopbarLink.from(@app_link)
+    end
+
     # The normalized topbar links (DocsKit::TopbarLink list), in declaration
     # order. Each configured Hash/TopbarLink is coerced via TopbarLink.from, so
     # the Shell only ever sees value objects. Blank/nil config yields [].

data/lib/docs_kit/landing_config.rb

@@ -26,6 +26,15 @@ module DocsKit
   # 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
 
@@ -81,6 +90,13 @@ module DocsKit
       { 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).
@@ -117,5 +133,28 @@ module DocsKit
         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

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

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

@@ -4,6 +4,7 @@ require "erb"
 require "yaml"
 require "rails/generators/base"
 require_relative "sync_report"
+require_relative "migration_registry"
 require_relative "../../../docs_kit/version"
 
 module DocsKit
@@ -44,6 +45,18 @@ module DocsKit
       AGENTS_END   = "<!-- END docs-kit -->"
       AGENTS_BLOCK_RE = /#{Regexp.escape(AGENTS_BEGIN)}.*#{Regexp.escape(AGENTS_END)}/m
 
+      # The config initializer — the one file every site has, so it carries the
+      # last-synced version stamp. See stamp_synced_version / run_migrations.
+      INITIALIZER = "config/initializers/docs_kit.rb"
+
+      # The inert comment recording which docs-kit version last synced this site.
+      # A future `--sync` reads it to run only the ordered migrations between that
+      # version and the gem's current one. Absent → the site predates the stamp
+      # (treated as the earliest version, so every migration applies).
+      SYNCED_STAMP_RE = /^#\s*docs-kit synced:\s*v(\d+\.\d+\.\d+)\s*$/
+
+      def self.synced_stamp(version = DocsKit::VERSION) = "# docs-kit synced: v#{version}"
+
       # The RuboCop wiring docs-kit injects. REQUIRE loads the cops;
       # INHERIT_GEM/INHERIT_PATH enable + scope them (see config/rubocop/docs_kit.yml).
       RUBOCOP_REQUIRE = "docs_kit/rubocop"
@@ -308,6 +321,43 @@ module DocsKit
         report.items.each { |item| say "  • #{item}" }
       end
 
+      # Run the ordered release-to-release migrations between the site's
+      # last-synced version and the gem's current one — the payoff of the version
+      # stamp. `--sync` only (a full install is a fresh scaffold, not an upgrade),
+      # and BEFORE stamp_synced_version restamps, so it reads the OLD version. An
+      # un-stamped site is treated as the earliest version (every migration runs).
+      # Migrations are warn-only-safe: what they can't automate they hand back as
+      # a checklist, printed like the drift report. The registry ships EMPTY at
+      # 1.0.x, so today this is a no-op that establishes the upgrade path.
+      def run_migrations
+        return unless options[:sync]
+
+        warnings = MigrationRegistry.default.migrate!(synced_version, destination_root, self)
+        return if warnings.empty?
+
+        say_status :warn, "migration steps to apply by hand:", :yellow
+        warnings.each { |item| say "  • #{item}" }
+      end
+
+      # Record which docs-kit version this site is now synced at, so the NEXT
+      # `--sync` can run only the migrations after it. Injected as an inert
+      # comment at the top of the initializer (the one file every site has) —
+      # which create_initializer never rewrites, so stamping is its own step.
+      # Idempotent: updates a stale stamp in place, adds one when absent, and
+      # is a no-op when already current.
+      def stamp_synced_version
+        path = File.join(destination_root, INITIALIZER)
+        return unless File.exist?(path)
+
+        current = self.class.synced_stamp
+        source = File.read(path)
+        updated = source.match?(SYNCED_STAMP_RE) ? source.sub(SYNCED_STAMP_RE, current) : "#{current}\n#{source}"
+        return if updated == source
+
+        File.write(path, updated)
+        say_status :update, "#{INITIALIZER} (synced v#{DocsKit::VERSION})", :green
+      end
+
       def show_post_install
         return show_sync_summary if options[:sync]
 
@@ -328,6 +378,17 @@ module DocsKit
 
       private
 
+      # The docs-kit version this site was last synced at, read from the
+      # initializer's stamp. Un-stamped (a site created before the stamp landed,
+      # or a fresh skeleton) → "0.0.0", the earliest version, so every migration
+      # applies. Read BEFORE stamp_synced_version overwrites it.
+      def synced_version
+        path = File.join(destination_root, INITIALIZER)
+        return "0.0.0" unless File.exist?(path)
+
+        File.read(path)[SYNCED_STAMP_RE, 1] || "0.0.0"
+      end
+
       def show_sync_summary
         say_status :info, "docs-kit synced.", :green
         say <<~MSG

data/lib/generators/docs_kit/install/migration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DocsKit
+  module Generators
+    # One ordered, versioned upgrade step between two docs-kit releases. `to` is
+    # the version the migration belongs to (the release that introduced the
+    # change); the registry runs it when a site's last-synced version is BELOW
+    # `to`. The block receives the site's `(destination_root, generator)` so it
+    # can read/rewrite files via the generator's helpers, and returns the list
+    # of manual-cleanup warnings it could NOT safely automate.
+    #
+    # Warn-only-safe by contract (the #24 drift pattern): a migration does what
+    # it can idempotently — never a destructive rewrite of a hand-edited line —
+    # and hands back strings for whatever needs a human. A `nil` return means
+    # "nothing to warn about".
+    class Migration
+      attr_reader :to, :description
+
+      def initialize(to:, description:, &block)
+        @to = Gem::Version.new(to.to_s)
+        @description = description
+        @block = block
+      end
+
+      # Run the transform against the site. Returns the (possibly empty) list of
+      # manual-cleanup warnings — never nil, so callers can flat-map safely.
+      def call(root, generator)
+        Array(@block.call(root, generator))
+      end
+    end
+  end
+end

data/lib/generators/docs_kit/install/migration_registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "migration"
+require_relative "../../../docs_kit/version"
+
+module DocsKit
+  module Generators
+    # The ordered set of release-to-release migrations `--sync` applies. Given a
+    # site's last-synced version, it selects the migrations the site hasn't run
+    # yet — those in the half-open range `(from_version, upto]`: ABOVE the site
+    # version (a migration AT the site version is already applied) and no newer
+    # than the installed gem — and runs them in ascending order, collecting the
+    # warn-only messages each couldn't safely automate.
+    #
+    # The `upto` ceiling (default: the installed gem version) matters because
+    # `--sync` restamps the site to DocsKit::VERSION afterward. A migration whose
+    # `to` sat ABOVE the gem version would then still exceed the new stamp and
+    # re-run on EVERY sync forever. It can't legitimately exist anyway (a site
+    # can't have "arrived" at a release it doesn't have), so it's filtered out.
+    #
+    # `.default` is the registry the generator uses. It SHIPS EMPTY at 1.0.x —
+    # the mechanism (stamp the synced version, detect the gap, run ordered
+    # transforms) is the deliverable; the first concrete `1.x → 1.y` transform is
+    # a one-line `Migration.new(...)` addition here once a release needs one.
+    class MigrationRegistry
+      def initialize(migrations = [])
+        @migrations = migrations.sort_by(&:to)
+      end
+
+      # The registry the install generator runs during `--sync`. Empty today.
+      def self.default
+        @default ||= new(MIGRATIONS)
+      end
+
+      # No migrations to register yet — the mechanism is the 1.0 deliverable.
+      # Add ordered `Migration.new(to: "1.x.0", description: "...") { ... }`
+      # entries here as future releases change config knobs, routes, or templates.
+      MIGRATIONS = [].freeze
+
+      # The migrations a site last synced at `from_version` still needs, ascending
+      # by version — those in `(from_version, upto]`. `upto` defaults to the
+      # installed gem version so a migration targeting an unreleased version never
+      # applies (and never re-runs against the post-sync stamp).
+      def applicable(from_version, upto: DocsKit::VERSION)
+        from = Gem::Version.new(from_version.to_s)
+        ceiling = Gem::Version.new(upto.to_s)
+        @migrations.select { |migration| migration.to > from && migration.to <= ceiling }
+      end
+
+      # Run every applicable migration in order against the site, returning the
+      # flattened list of manual-cleanup warnings they couldn't safely automate.
+      def migrate!(from_version, root, generator, upto: DocsKit::VERSION)
+        applicable(from_version, upto: upto).flat_map { |migration| migration.call(root, generator) }
+      end
+    end
+  end
+end

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

@@ -1,3 +1,4 @@
+<%= self.class.synced_stamp %>
 # frozen_string_literal: true
 
 # docs-kit configuration — everything that makes this site look like YOUR docs.
@@ -20,6 +21,12 @@ Rails.application.config.to_prepare do
     # docs live under a subpath:
     # c.brand_href = "/docs"
 
+    # Docs embedded in a bigger app? Add the way BACK to that app — a labeled
+    # link rendered once in the topbar, right after the brand. brand_href is the
+    # DOCS home (brand, sidebar, and the page masthead's "← Docs home" all
+    # follow it); app_link is the APP home. Unset (the default) renders nothing.
+    # c.app_link = { href: "/", label: "Back to the app" }
+
     # Repo/social links in the topbar, next to the theme switcher. Each renders
     # as an icon-only button; `icon` is a shipped brand mark (:github, :gitlab,
     # :discord, :x, :rubygems, :bluesky, :mastodon, :slack, :whatsapp, :telegram,
@@ -109,6 +116,9 @@ Rails.application.config.to_prepare do
     # 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."

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.0.7
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -234,6 +234,8 @@ files:
 - lib/docs_kit/version.rb
 - lib/generators/docs_kit/install/USAGE
 - lib/generators/docs_kit/install/install_generator.rb
+- lib/generators/docs_kit/install/migration.rb
+- lib/generators/docs_kit/install/migration_registry.rb
 - lib/generators/docs_kit/install/sync_report.rb
 - lib/generators/docs_kit/install/templates/Dockerfile.tt
 - lib/generators/docs_kit/install/templates/agents_md.erb