docs-kit 1.0.7 → 1.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa41c41824768d1db2a5ad5a7ba9b983b0f81032c8b5a3f80277e2611e203449
-  data.tar.gz: 60cd31b54d83c9c6920ff48d27ec177f81b7a240fdf513e65f9617837cc6c738
+  metadata.gz: 78cf5f2d5a4636b8b0c603f3d3b238aeb68c100fd0133edb16d52ce56ade4c39
+  data.tar.gz: 50acc90365594b546ba40887c976eb6f7c6e1eca7389b834c6793cd0490bbfb9
 SHA512:
-  metadata.gz: e23f649705ac6216e4961c389eab64965961023123937364e4915b608264bf994ec0885c1958929884449d4eb4f6d9202ed6a5fa7fb9dd373c6a2202e8850ea1
-  data.tar.gz: 0a047f0b8b45fdce21b9121b13461a5c003ec307586ef4b49bbb3ead0c4d79f44db00a243eda7792fc5be173f3b135195efad4212360527cb2ef5e143eafd5e5
+  metadata.gz: b650c98a593eda398bafde41a07ed5ad01325d5392b113a8cfebedc06bb71519e139f846b8e6e259c106c8b23a64a2af4c9a0ab5ab1efd1b2b524764be72fa07
+  data.tar.gz: 29c352545d1ffcd4ba93461b2df5582663b79d86db835866fc6b2d543018d5d2e0034e43f24f2f67d0ebd953b89e65788a276484901c71b693fe95040668b8ad

data/README.md

@@ -166,6 +166,10 @@ DocsKit.configure do |c|
   # once in the topbar, right after the brand. Unset (default) renders nothing.
   c.app_link = { href: "/", label: "Back to the app" }
 
+  # Your own mark in the topbar + sidebar header instead of the text brand.
+  c.brand_logo   = { paths: ["M4 2h9l5 5…Z"], viewbox: "0 0 81 45" }
+  c.topbar_brand = :mobile_only                             # drop the desktop duplicate (default :always)
+
   # 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 },
@@ -185,6 +189,12 @@ 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.
 
+The registry's page groups ("Getting started", "REST API", …) are the top level
+of the rendered menu — each an open, collapsible section. The heading above them
+only appears when you register **several** headings, and then as a static label
+(no fold): a site with one registry gets no redundant "Documentation" level, and
+nothing in the sidebar is indented deeper than group → page.
+
 ### The two homes, the brand link, and dark code themes
 
 These knobs cover what sites used to shim by subclassing `DocsUI::Shell` or
@@ -194,6 +204,8 @@ overriding route helpers:
 |------|---------|--------------|
 | `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.brand_logo` | `nil` | Your **brand mark**, rendered inside the brand anchor of BOTH the topbar and the sidebar header in place of the text `c.brand` (which stays the accessible name / `aria-label` fallback). Unset renders the text brand, byte-identical to before. Takes exactly one of five forms — see [The brand mark](#the-brand-mark) below. |
+| `c.topbar_brand` | `:always` | Where the topbar renders the brand. At the drawer-pinned breakpoint (`lg:`) the sidebar brand is always visible, so the topbar copy is a duplicate — `:mobile_only` hides it there (`lg:hidden`). The default keeps today's markup verbatim. |
 | `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]`). |
 
@@ -203,6 +215,33 @@ blocks with no JavaScript and no flash. The Rouge CSS is inlined per block
 (not part of the Tailwind build), so the [theme-sync invariant](#css--the-canonical-build)
 is unaffected — a `code_theme_dark` doesn't need a CSS rebuild.
 
+### The brand mark
+
+`c.brand_logo` replaces the text brand in the shell chrome (topbar + sidebar
+header) with your own mark — no more copying private `Shell`/`Sidebar` methods
+that go stale on upgrades. It takes **exactly one** of five forms (mixing forms,
+or a malformed value, raises at config time):
+
+```ruby
+c.brand_logo = { svg: "M4 2h9l5 5…Z", viewbox: "0 0 22 24", label: "Acme" } # one path-d
+c.brand_logo = { paths: ["M4 2…Z", "M9 7…Z"], viewbox: "0 0 81 45" }        # multi-path wordmark
+c.brand_logo = { markup: File.read("mark.svg") }                            # raw <svg> markup, embedded verbatim
+c.brand_logo = { file: "app/assets/images/mark.svg" }                       # a .svg file, embedded inline
+c.brand_logo = { src: "logo.png", alt: "Acme" }                             # an <img> from the asset pipeline
+```
+
+- The `svg:`/`paths:` forms render with `fill="currentColor"`, so the mark
+  **recolors with the active daisyUI theme**. `markup:`/`file:` are embedded
+  as-authored — use `currentColor` inside them to stay theme-adaptive. An
+  `src:` `<img>` **cannot** inherit `currentColor` and won't adapt.
+- `markup:`/`file:` embed your own SVG verbatim (they are your site's content,
+  same trust domain as your views); both are shape-checked to be an `<svg>`
+  element at config time, and a `file:` re-reads on change in development.
+- `label:`/`alt:` name the mark for assistive tech; unset, the mark falls back
+  to `c.brand`. The sidebar keeps the `version_badge` next to the mark.
+- Sizing is fixed per surface (topbar `h-6`, sidebar `h-7`, landing hero `h-9`).
+- `c.landing.logo` (the landing-hero mark) accepts the same five forms.
+
 ### Topbar links (repo & social)
 
 Point readers at your source repo, chat, or socials from the topbar (next to the

data/app/components/docs_ui/landing.rb

@@ -31,9 +31,6 @@ 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
@@ -63,20 +60,12 @@ 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.
+    # The brand mark — the shared DocsUI::Logo renderer (any DocsKit::BrandLogo
+    # form) at hero size. 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
+      render DocsUI::Logo.new(mark, class: "h-9 w-auto text-primary")
     end
 
     def eyebrow
@@ -162,15 +151,17 @@ module DocsUI
       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) }
+          # A lone heading would just repeat the h2 above (often literally
+          # "Documentation"), so only label the columns when there are several.
+          groups.each { |heading, items| doc_index_group(heading, items, labeled: groups.size > 1) }
         end
       end
     end
 
-    def doc_index_group(heading, items)
+    def doc_index_group(heading, items, labeled:)
       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
+        h3(class: "text-xs font-semibold uppercase tracking-wide text-base-content/40") { heading } if labeled
+        ul(class: labeled ? "mt-3 flex flex-col gap-2" : "flex flex-col gap-2") do
           items.each { |item| li { a(href: item.href, class: "link link-hover text-sm") { item.label } } }
         end
       end

data/app/components/docs_ui/logo.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # Renders a DocsKit::BrandLogo (config.brand_logo / config.landing.logo) as the
+  # brand mark — an inline currentColor <svg> (theme-adaptive), a verbatim
+  # site-authored <svg> embed, or an <img>.
+  #
+  #   render DocsUI::Logo.new(config.brand_logo, class: "h-6 w-auto", label: config.brand)
+  #
+  # label: is the accessible-name fallback when the logo itself carries none
+  # (callers pass config.brand, so the mark always announces the site).
+  #
+  # The svg:/paths: forms emit each path-d as an ordinary Phlex-escaped
+  # attribute — config free text never bypasses the escape. The markup:/file:
+  # forms DO embed markup verbatim via raw(safe(...)): that content is the
+  # site's own deliberately-configured SVG (its initializer / its asset file —
+  # the same trust domain as the site's own views, which can already render
+  # anything), not third-party free text, and DocsKit::BrandLogo shape-checks it
+  # to be an <svg> element at config time. That authored-by-the-trusting-site
+  # rationale is the same carve-out DocsUI::BrandMark uses for its gem-authored
+  # path constants.
+  class Logo < Phlex::HTML
+    # For the src: image form — resolve the asset path through the site's
+    # pipeline to its digested /assets URL, exactly like DocsUI::Landing's img.
+    include Phlex::Rails::Helpers::ImageURL
+
+    def initialize(logo, label: nil, **attributes)
+      @logo = DocsKit::BrandLogo.from(logo)
+      @label = label
+      @attributes = attributes
+    end
+
+    def view_template
+      if @logo.image?
+        img(src: resolved_src, alt: accessible_name.to_s, **@attributes)
+      elsif @logo.embed?
+        embedded_svg
+      else
+        inline_svg
+      end
+    end
+
+    private
+
+    def accessible_name = @logo.label || @label
+
+    # The svg:/paths: forms: a currentColor mark that recolors with the active
+    # daisyUI theme; every path-d is an escaped attribute value.
+    def inline_svg
+      svg(viewBox: @logo.viewbox, fill: "currentColor", role: "img",
+          aria_label: accessible_name, **@attributes) do |s|
+        s.title { accessible_name } if accessible_name
+        @logo.paths.each { |d| s.path(d: d) }
+      end
+    end
+
+    # The markup:/file: forms: the site's own <svg> embedded verbatim (see the
+    # class comment for the trust rationale) inside a wrapper that carries the
+    # caller's sizing — the inner svg fills it. Literal arbitrary variants so
+    # Tailwind scans them from this file.
+    def embedded_svg
+      classes = [@attributes[:class], "inline-flex [&>svg]:h-full [&>svg]:w-auto"].compact.join(" ")
+      span(role: "img", aria_label: accessible_name, **@attributes, class: classes) do
+        raw(safe(@logo.svg_markup))
+      end
+    end
+
+    # The digested asset URL when a view context is present; off a request (an
+    # isolated render) degrade to the raw src — the DocsUI::MetaTags posture.
+    def resolved_src
+      view_context ? image_url(@logo.src) : @logo.src
+    end
+  end
+end

data/app/components/docs_ui/shell.rb

@@ -156,7 +156,7 @@ module DocsUI
         div(class: "flex-1 items-center gap-2") do
           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 }
+          a(href: config.brand_href, class: topbar_brand_classes) { brand_mark }
           app_home_link
         end
         render DocsUI::SearchBox.new if config.search_enabled?
@@ -169,6 +169,26 @@ module DocsUI
       end
     end
 
+    # The brand anchor's classes. config.topbar_brand = :mobile_only adds
+    # lg:hidden — at the drawer-pinned breakpoint the sidebar brand is already
+    # visible, so a site can drop the duplicate. The default (:always) keeps
+    # the pre-knob classes verbatim.
+    def topbar_brand_classes
+      base = "btn btn-ghost text-lg font-bold"
+      config.topbar_brand == :mobile_only ? "#{base} lg:hidden" : base
+    end
+
+    # The brand: the configured mark (config.brand_logo) when set, else the
+    # text brand — byte-identical to before for a site that sets nothing. The
+    # text brand stays the mark's accessible-name fallback.
+    def brand_mark
+      if (logo = config.brand_logo)
+        render DocsUI::Logo.new(logo, class: "h-6 w-auto", label: config.brand)
+      else
+        plain config.brand
+      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.

data/app/components/docs_ui/sidebar.rb

@@ -8,6 +8,11 @@ module DocsUI
   #
   # nav_groups is an ordered Hash:
   #   { "Heading" => { "Subgroup" => [DocsKit::NavItem, ...] } }
+  #
+  # Subgroups are the top level of the rendered menu. A lone heading (the common
+  # single-registry site) is not rendered at all — the brand masthead already
+  # labels the sidebar; with several headings, each renders as a STATIC
+  # `.menu-title` label (no fold) and only subgroups collapse.
   class Sidebar < Phlex::HTML
     include Phlex::Rails::Helpers::Request
     include DaisyUI
@@ -29,7 +34,8 @@ module DocsUI
         header_section
         div(class: "flex-1 overflow-y-auto px-2 pb-6") do
           Menu(class: "w-full gap-1") do
-            nav_groups.each { |heading, grouped| nav_group(heading, grouped) }
+            groups = nav_groups.reject { |_, grouped| grouped.nil? || grouped.empty? }
+            groups.each { |heading, grouped| nav_group(heading, grouped, labeled: groups.size > 1) }
           end
         end
       end
@@ -42,27 +48,37 @@ module DocsUI
 
     def header_section
       div(class: "flex min-h-16 items-center gap-2 px-4") do
-        a(href: config.brand_href, class: "text-lg font-bold text-base-content") { config.brand }
+        a(href: config.brand_href, class: "text-lg font-bold text-base-content") { brand_mark }
         badge = config.version_badge_text
         span(class: "badge badge-sm badge-ghost") { badge } if badge
       end
     end
 
-    # A top-level collapsible group (e.g. "Docs") holding collapsible sub-groups
-    # (e.g. "Guide", "Examples"). `grouped` is a { subgroup => [items] } Hash.
-    def nav_group(heading, grouped)
-      return if grouped.nil? || grouped.empty?
+    # The brand: the configured mark (config.brand_logo) when set, else the
+    # text brand — byte-identical to before for a site that sets nothing.
+    # Slightly taller than the topbar's h-6: this is the masthead.
+    def brand_mark
+      if (logo = config.brand_logo)
+        render DocsUI::Logo.new(logo, class: "h-7 w-auto", label: config.brand)
+      else
+        plain config.brand
+      end
+    end
 
-      li do
-        details(open: true) do
-          summary(class: "text-xs font-semibold uppercase tracking-wider text-base-content/50 #{MARKER_RESET}") do
-            heading
-          end
-          ul do
-            grouped.each { |subgroup, items| nav_subgroup(subgroup, items) }
-          end
+    # A top-level group (e.g. "Docs") holding collapsible sub-groups (e.g.
+    # "Guide", "Examples"). `grouped` is a { subgroup => [items] } Hash. The
+    # heading label only renders when the sidebar shows SEVERAL groups
+    # (labeled:) — as a static `.menu-title`, never a <details>, so subgroups
+    # stay at the menu's top level instead of gaining a nesting indent. The
+    # mt-4/first:mt-0 pair is the breathing room between one group's links and
+    # the next group's label.
+    def nav_group(heading, grouped, labeled:)
+      if labeled
+        li(class: "menu-title mt-4 text-xs font-semibold uppercase tracking-wider text-base-content/50 first:mt-0") do
+          heading
         end
       end
+      grouped.each { |subgroup, items| nav_subgroup(subgroup, items) }
     end
 
     # A collapsible sub-group: its title is a <summary> so the whole section folds

data/lib/docs_kit/brand_logo.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # The normalized brand mark for the shell chrome (config.brand_logo) and the
+  # landing hero (config.landing.logo). A site configures a Hash in exactly one
+  # of five forms; DocsUI::Logo renders the result:
+  #
+  #   { svg: "M0 0Z", viewbox: "0 0 24 24", label: "Acme" }   # one path-d (landing-compat)
+  #   { paths: ["M0 0Z", "M4 4Z"], viewbox: "…", label: "…" } # multi-path wordmark
+  #   { markup: "<svg …>…</svg>", label: "Acme" }             # raw SVG markup, embedded verbatim
+  #   { file: "app/assets/images/mark.svg", label: "Acme" }   # a .svg file, embedded inline
+  #   { src: "logo.png", alt: "Acme" }                        # an <img> (not theme-adaptive)
+  #
+  # The svg:/paths: forms render each `d` as an ordinary Phlex-escaped attribute.
+  # The markup:/file: forms embed SITE-AUTHORED markup verbatim (see DocsUI::Logo
+  # for the trust rationale); both are shape-checked here — the content must be an
+  # <svg> element — so a mis-pasted snippet fails loudly at config time, never as
+  # a silently broken (or script-bearing) header. Mixing forms, or giving none,
+  # is ambiguous config and raises. `label`/`alt` fall back to each other so
+  # either knob names the mark for assistive tech.
+  #
+  # A file: mark memoizes its content and re-reads on an mtime change (the
+  # Configuration#openapi_document posture), so editing the SVG in development
+  # shows up without a server restart.
+  class BrandLogo
+    # The config keys that each select a render form — exactly one must be given.
+    FORM_KEYS = %i[svg paths markup file src].freeze
+
+    # A loose "is this an <svg> element" shape check for the markup:/file: forms.
+    SVG_SHAPE = /\A\s*<svg[\s>]/i
+
+    DEFAULT_VIEWBOX = "0 0 24 24"
+
+    attr_reader :paths, :viewbox, :markup, :file, :src
+
+    # Coerce a config value (Hash with symbol or string keys, or an
+    # already-normalized BrandLogo) into a BrandLogo.
+    def self.from(logo)
+      return logo if logo.is_a?(self)
+
+      new(logo.to_h)
+    end
+
+    def initialize(attrs = {})
+      attrs = attrs.transform_keys(&:to_sym)
+      given = attrs.slice(*FORM_KEYS).compact
+      unless given.size == 1
+        raise ArgumentError,
+              "brand_logo takes exactly one of #{FORM_KEYS.inspect} (got #{given.keys.inspect})"
+      end
+
+      @viewbox = attrs[:viewbox] || DEFAULT_VIEWBOX
+      @label = attrs[:label]
+      @alt = attrs[:alt]
+      build_form(given.keys.first, attrs)
+    end
+
+    # The single path-d, for the landing-compat svg: shape (first of #paths).
+    def svg = paths&.first
+
+    def inline? = !paths.nil?
+    def markup? = !markup.nil?
+    def file? = !file.nil?
+    def image? = !src.nil?
+
+    # Whether the mark embeds site-authored markup verbatim (markup: or file:).
+    def embed? = markup? || file?
+
+    # The accessible name — label falls back to alt (and vice versa) so a site
+    # setting either names the mark; nil defers to the render-time brand fallback.
+    def label = @label || @alt
+    def alt = @alt || @label
+
+    # The markup to embed: the literal markup: string, or the file's content —
+    # memoized per mtime so a dev edit re-reads without a restart.
+    def svg_markup
+      return @markup if markup?
+
+      mtime = begin
+        @file.mtime
+      rescue StandardError
+        nil
+      end
+      return @file_content if defined?(@file_content) && @file_mtime == mtime
+
+      @file_mtime = mtime
+      @file_content = check_svg_shape!(@file.read, "file #{@file}")
+    end
+
+    private
+
+    # Store the one given form. file: primes #svg_markup immediately so a bad
+    # file fails at config time (boot), not on first render.
+    def build_form(form, attrs)
+      case form
+      when :svg, :paths then @paths = Array(attrs[:paths] || attrs[:svg]).map(&:to_s)
+      when :markup then @markup = check_svg_shape!(attrs[:markup].to_s, "markup")
+      when :src then @src = attrs[:src]
+      when :file
+        @file = resolve_file!(attrs[:file])
+        svg_markup
+      end
+    end
+
+    # Validate + resolve the file: form eagerly, so a bad path fails at config
+    # time (boot), not on first render. Relative paths resolve against Rails.root
+    # when Rails is loaded, else the process working directory.
+    def resolve_file!(file)
+      path = Pathname.new(file.to_s)
+      path = Rails.root.join(path) if path.relative? && defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+      raise ArgumentError, "brand_logo file must be a .svg (got #{path.basename})" unless path.extname.casecmp?(".svg")
+      raise ArgumentError, "brand_logo file not found: #{path}" unless path.file?
+
+      path
+    end
+
+    # The markup:/file: shape guard — the content must BE an <svg> element.
+    def check_svg_shape!(content, source)
+      return content if content.match?(SVG_SHAPE)
+
+      raise ArgumentError, "brand_logo #{source} must be an <svg> element (got #{content[0, 40].inspect})"
+    end
+  end
+end

data/lib/docs_kit/configuration.rb

@@ -193,6 +193,39 @@ module DocsKit
     # sidebar, and page-masthead links). Read via #app_link, never @app_link.
     attr_writer :app_link
 
+    # The opt-in shell brand mark, rendered by BOTH the topbar and the sidebar
+    # header in place of the text #brand (which stays the accessible-name
+    # fallback). A Hash in exactly one of the DocsKit::BrandLogo forms —
+    # svg:/paths: (inline path-d, theme-adaptive via currentColor), markup:/file:
+    # (site-authored <svg> embedded verbatim), or src: (an <img>, NOT
+    # theme-adaptive) — or an already-built BrandLogo. Defaults to nil → the
+    # text brand renders and the chrome is byte-identical to before. Sibling of
+    # c.landing.logo, which is the landing-hero mark. Read via #brand_logo,
+    # never @brand_logo.
+    def brand_logo=(value)
+      @brand_logo = nil
+      @brand_logo_raw = value
+    end
+
+    # Where the topbar renders the brand: :always (the default — byte-compat),
+    # or :mobile_only, which hides it at the drawer-pinned breakpoint (lg:)
+    # where the sidebar brand is already visible, deduplicating the mark.
+    attr_reader :topbar_brand
+
+    # The topbar-brand placements. At lg: the sidebar (with its own brand) is
+    # pinned open, so :mobile_only drops the duplicate; :always keeps it.
+    TOPBAR_BRAND_MODES = %i[always mobile_only].freeze
+
+    def topbar_brand=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless TOPBAR_BRAND_MODES.include?(mode)
+        raise ArgumentError,
+              "topbar_brand must be one of #{TOPBAR_BRAND_MODES.inspect} (got #{value.inspect})"
+      end
+
+      @topbar_brand = mode
+    end
+
     # 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
@@ -274,6 +307,9 @@ module DocsKit
       @app_link = nil
       @topbar_links = []
       @openapi = nil
+      @brand_logo = nil
+      @brand_logo_raw = nil
+      @topbar_brand = :always
     end
 
     # The normalized App Home link (a DocsKit::TopbarLink), or nil when unset —
@@ -284,6 +320,17 @@ module DocsKit
       DocsKit::TopbarLink.from(@app_link)
     end
 
+    # The normalized shell brand mark (a DocsKit::BrandLogo), or nil when unset.
+    # Memoized (and invalidated on reassignment) — unlike #app_link's rebuild-
+    # per-read, because a file: mark shape-checks and reads its SVG on build;
+    # per-render re-normalization would repeat that IO. A malformed value raises
+    # here, on first read — loud, never a silently broken header.
+    def brand_logo
+      return if @brand_logo_raw.nil?
+
+      @brand_logo ||= DocsKit::BrandLogo.from(@brand_logo_raw)
+    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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "brand_logo"
+
 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.
@@ -90,11 +92,11 @@ 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.
+    # The hero logo as a normalized DocsKit::BrandLogo, or nil when unset.
     def hero_logo
       return if @logo.nil?
 
-      Logo.from(@logo)
+      DocsKit::BrandLogo.from(@logo)
     end
 
     # One hero call-to-action button. `style` maps to a daisyUI btn variant
@@ -134,27 +136,9 @@ module DocsKit
       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
+    # The hero brand logo shape now lives in DocsKit::BrandLogo (shared with the
+    # shell's config.brand_logo); the old nested name stays as an alias so any
+    # site referencing LandingConfig::Logo keeps working.
+    Logo = DocsKit::BrandLogo
   end
 end

data/lib/docs_kit/version.rb

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

data/lib/docs_kit.rb

@@ -58,6 +58,9 @@ loader.ignore(File.expand_path("docs_kit/configuration.rb", __dir__))
 # 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__))
+# Required eagerly by landing_config.rb (the LandingConfig::Logo alias resolves
+# it at require time, before this loader is set up), so ignore it here too.
+loader.ignore(File.expand_path("docs_kit/brand_logo.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

@@ -21,6 +21,23 @@ Rails.application.config.to_prepare do
     # docs live under a subpath:
     # c.brand_href = "/docs"
 
+    # Your own mark in the topbar + sidebar header instead of the text brand
+    # (which stays the accessible name). Exactly ONE of these forms:
+    #   paths:  — inline path-d list; fills with currentColor, so the mark
+    #             recolors with the active theme (also `svg:` for one path)
+    #   markup: — a full <svg>…</svg> string, embedded verbatim (use
+    #             fill="currentColor" in it to stay theme-adaptive)
+    #   file:   — a .svg under this app (e.g. "app/assets/images/mark.svg"),
+    #             embedded inline at render — same currentColor advice
+    #   src:    — an image asset path/URL rendered as an <img>; note an <img>
+    #             canNOT inherit currentColor, so it won't adapt to the theme
+    # c.brand_logo = { paths: ["M4 2h9l5 5…Z"], viewbox: "0 0 81 45", label: "<%= app_brand %>" }
+
+    # On desktop (lg:) the pinned sidebar already shows the brand, so the topbar
+    # copy is a duplicate. :mobile_only hides the topbar brand at lg:; the
+    # default (:always) keeps it everywhere.
+    # c.topbar_brand = :mobile_only
+
     # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docs-kit
 version: !ruby/object:Gem::Version
-  version: 1.0.7
+  version: 1.0.8
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -175,6 +175,7 @@ files:
 - app/components/docs_ui/icon.rb
 - app/components/docs_ui/json_response.rb
 - app/components/docs_ui/landing.rb
+- app/components/docs_ui/logo.rb
 - app/components/docs_ui/markdown.rb
 - app/components/docs_ui/markdown_action.rb
 - app/components/docs_ui/meta_tags.rb
@@ -205,6 +206,7 @@ files:
 - lib/docs_kit/api_client.rb
 - lib/docs_kit/api_request.rb
 - lib/docs_kit/api_templates.rb
+- lib/docs_kit/brand_logo.rb
 - lib/docs_kit/configuration.rb
 - lib/docs_kit/controller.rb
 - lib/docs_kit/engine.rb