docs-kit 0.1.0

data/lib/docs_kit/rubocop.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Entry point for docs-kit's custom RuboCop cops. A consuming site loads them
+# with a single line in its `.rubocop.yml`:
+#
+#   require:
+#     - docs_kit/rubocop
+#   inherit_gem:
+#     docs-kit: config/rubocop/docs_kit.yml
+#
+# RuboCop is required LAZILY here — it is a development-time dependency of the
+# HOST app (every generated docs site has `rubocop` in its Gemfile), never a
+# runtime dependency of docs-kit itself. Requiring this file outside a RuboCop
+# run (e.g. if a stray `require` reaches it) still works: it pulls in rubocop on
+# demand rather than assuming it is already loaded.
+require "rubocop"
+
+require_relative "../rubocop/cop/docs_kit/render_component_preferred"
+require_relative "../rubocop/cop/docs_kit/escaped_interpolation_in_heredoc"

data/lib/docs_kit/search_hit.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # One ranked search result. Built by DocsKit::SearchIndex#search and rendered by
+  # DocsUI::SearchResults (html) / serialized to JSON for the docs-nav palette.
+  #
+  #   page_title    — the page the hit lives on (results group by this)
+  #   section_title — the `## ` section, or nil for a page-intro hit
+  #   href          — the page href + "#anchor" (nil section → bare page href)
+  #   snippet       — an HTML-safe excerpt around the match, the term in <mark>
+  #   score         — the rank weight (title > heading > body); higher wins
+  SearchHit = Data.define(:page_title, :section_title, :href, :snippet, :score) do
+    def initialize(page_title:, href:, snippet:, score:, section_title: nil)
+      super
+    end
+
+    # The label a result row shows: "Page → Section", or just the page title for
+    # a page-intro hit.
+    def label
+      section_title ? "#{page_title} → #{section_title}" : page_title
+    end
+
+    # JSON shape the palette fetches (matches #label / #href / #snippet).
+    def as_json(*)
+      { "label" => label, "href" => href, "snippet" => snippet }
+    end
+  end
+end

data/lib/docs_kit/search_index/snippet.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module DocsKit
+  class SearchIndex
+    # Builds the HTML-safe excerpt shown under a search result: a short window of
+    # text centered on the first query-token match, with every token wrapped in
+    # <mark>. Surrounding text is HTML-escaped so an angle bracket in the source
+    # can never inject markup — the returned String is safe to render.
+    class Snippet
+      # Characters of context on either side of the first match.
+      RADIUS = 80
+
+      def self.build(text, tokens)
+        new(text, tokens).build
+      end
+
+      def initialize(text, tokens)
+        @flat = text.to_s.gsub(/\s+/, " ").strip
+        @tokens = tokens
+      end
+
+      def build
+        highlight(window)
+      end
+
+      private
+
+      # A ~RADIUS-on-each-side slice around the first token match, with leading/
+      # trailing ellipses when the window is cut from a longer body. No match (the
+      # hit was title-only) → the head of the text.
+      def window
+        idx = first_match_index
+        return head if idx.nil?
+
+        start = [idx - RADIUS, 0].max
+        finish = [idx + RADIUS, @flat.length].min
+        "#{'…' if start.positive?}#{@flat[start...finish].strip}#{'…' if finish < @flat.length}"
+      end
+
+      def head
+        slice = @flat[0, RADIUS * 2].to_s.strip
+        @flat.length > RADIUS * 2 ? "#{slice}…" : slice
+      end
+
+      def first_match_index
+        down = @flat.downcase
+        @tokens.filter_map { |token| down.index(token) }.min
+      end
+
+      # Escape the window, then wrap each token's (case-insensitive) occurrences in
+      # <mark>. Tokens are escaped before matching so the search runs against the
+      # same escaped text and no token can smuggle in HTML.
+      def highlight(window)
+        escaped = CGI.escapeHTML(window)
+        @tokens.each do |token|
+          pattern = Regexp.new(Regexp.escape(CGI.escapeHTML(token)), Regexp::IGNORECASE)
+          escaped = escaped.gsub(pattern) { |match| "<mark>#{match}</mark>" }
+        end
+        escaped
+      end
+    end
+  end
+end

data/lib/docs_kit/search_index.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module DocsKit
+  # An in-memory docs search index, built straight from the pages' Markdown twins
+  # — zero authoring, no external service, no build step. This is the structural
+  # replacement for the hand-maintained "second registry" + regex-parsed text a
+  # site used to keep: the twin already IS the page's content, split on its `## `
+  # headings into searchable sections.
+  #
+  #   DocsKit::SearchIndex.new(triples).search("theme switcher")
+  #
+  # `triples` is [[page_title, page_href, markdown], ...] — the controller renders
+  # each registry page through DocsKit::MarkdownExport and hands the triples in,
+  # exactly as DocsKit::LlmsText separates pure shaping from the controller's
+  # rendering. So the whole index + scorer is unit-testable with no Rails.
+  #
+  # One entry per section (plus a page-intro entry for the text before the first
+  # `## `). Scoring is plain Ruby: case-insensitive token match, all tokens must
+  # hit (AND), a title hit outranks a heading hit outranks a body hit. Results cap
+  # at MAX_RESULTS with an HTML-safe snippet around the match (the term in
+  # <mark>). No dependencies, no fuzzy matching (revisit if usage demands it).
+  class SearchIndex
+    # Field weights — a match in the page title beats a section heading beats body
+    # text, so the most on-topic section floats up.
+    TITLE_WEIGHT = 100
+    HEADING_WEIGHT = 10
+    BODY_WEIGHT = 1
+
+    # Never return more than this — a docs site is tens of pages, and a reader
+    # scans the top matches, not a hundred.
+    MAX_RESULTS = 20
+
+    # An indexed section (or page intro). `haystacks` holds the lowercased text of
+    # each weighted field so scoring is a simple include? per token.
+    #
+    # The page title is searchable ONLY on the page-intro entry (section_title
+    # nil), not on every section: a title token matches all sections of a page
+    # equally, so weighting each section by the title would flood the results with
+    # near-identical rows from one page. A pure title match therefore surfaces
+    # once (the intro), while a section still ranks on its own heading/body.
+    Entry = Struct.new(:page_title, :section_title, :href, :body, keyword_init: true) do
+      # { weight => lowercased searchable text } for this entry.
+      def haystacks
+        @haystacks ||= begin
+          fields = {
+            HEADING_WEIGHT => section_title.to_s.downcase,
+            BODY_WEIGHT => body.to_s.downcase
+          }
+          fields[TITLE_WEIGHT] = page_title.to_s.downcase if section_title.nil?
+          fields
+        end
+      end
+    end
+
+    # triples: [[page_title, page_href, markdown], ...].
+    def initialize(triples = [])
+      @entries = triples.flat_map { |title, href, markdown| entries_for(title, href, markdown) }
+    end
+
+    attr_reader :entries
+
+    # The top MAX_RESULTS SearchHits for `query`, best first. Blank query → [].
+    # Every whitespace-split token must match the entry somewhere (AND); the
+    # entry's score is the sum, per token, of the best field it matched.
+    def search(query)
+      tokens = tokenize(query)
+      return [] if tokens.empty?
+
+      scored = @entries.filter_map { |entry| score_entry(entry, tokens) }
+      scored.sort_by { |hit| [-hit.score, hit.page_title, hit.section_title.to_s] }
+            .first(MAX_RESULTS)
+    end
+
+    private
+
+    # Split a page's Markdown twin into entries: the intro text (before the first
+    # `## `) becomes a page-level entry; each `## Heading` starts a section entry
+    # whose href carries the recomputed anchor.
+    def entries_for(page_title, page_href, markdown)
+      intro, sections = split_sections(markdown.to_s)
+      built = []
+      built << build_entry(page_title, nil, page_href, intro) unless intro.strip.empty?
+      sections.each do |heading, body|
+        anchor = "#{page_href}##{slugify(heading)}"
+        built << build_entry(page_title, heading, anchor, body)
+      end
+      # A page with no intro and no sections (empty twin) still gets one entry, so
+      # its title is searchable.
+      built << build_entry(page_title, nil, page_href, "") if built.empty?
+      built
+    end
+
+    def build_entry(page_title, section_title, href, body)
+      Entry.new(page_title: page_title, section_title: section_title, href: href, body: body.strip)
+    end
+
+    # → [intro_text, [[heading, body], ...]]. Splits on lines that are exactly a
+    # level-2 ATX heading (`## Foo`), matching MarkdownExport's twin output. Scans
+    # line-by-line and toggles an in-fence flag on ``` / ~~~ fences so a `## `
+    # inside a code block stays body text — the rendered page never ids it, so a
+    # section entry there would carry a dead anchor.
+    def split_sections(markdown)
+      intro = +""
+      sections = []
+      in_fence = false
+      markdown.each_line do |line|
+        in_fence = !in_fence if line.match?(/^[ \t]*(```|~~~)/)
+        heading = line.match(/^\#\#[ \t]+(.+?)[ \t]*$/) unless in_fence
+        if heading
+          sections << [heading[1].strip, +""]
+        elsif sections.empty?
+          intro << line
+        else
+          sections.last[1] << line
+        end
+      end
+      [intro, sections]
+    end
+
+    # The section anchor the twin dropped: the same slug DocsUI::Section stamps on
+    # its <section id> (ActiveSupport #parameterize when available, else a minimal
+    # ASCII slug so the index works off-Rails too).
+    def slugify(text)
+      return text.parameterize if text.respond_to?(:parameterize)
+
+      text.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+
+    def tokenize(query)
+      query.to_s.downcase.split(/\s+/).reject(&:empty?)
+    end
+
+    # A SearchHit if EVERY token matched somewhere in the entry (AND), else nil.
+    # Each token scores the heaviest field it appears in; the entry score sums
+    # those, so a section matching more tokens (and in heavier fields) ranks higher.
+    def score_entry(entry, tokens)
+      total = 0
+      tokens.each do |token|
+        best = best_field_weight(entry, token)
+        return nil unless best # this token matched nothing → entry is out (AND)
+
+        total += best
+      end
+      SearchHit.new(
+        page_title: entry.page_title, section_title: entry.section_title,
+        href: entry.href, snippet: snippet_for(entry, tokens), score: total
+      )
+    end
+
+    # The heaviest field weight whose text contains `token`, or nil if none do.
+    def best_field_weight(entry, token)
+      entry.haystacks.select { |_weight, text| text.include?(token) }.keys.max
+    end
+
+    # An HTML-safe snippet around the match. Prefer the body; if the match is
+    # title-only (empty body), fall back to the section or page title so the row
+    # still has context. Snippet windowing + <mark> highlighting + escaping live
+    # in SearchIndex::Snippet.
+    def snippet_for(entry, tokens)
+      source = entry.body.to_s
+      if source.strip.empty?
+        source = entry.section_title.to_s.empty? ? entry.page_title.to_s : entry.section_title.to_s
+      end
+      Snippet.build(source, tokens)
+    end
+  end
+end

data/lib/docs_kit/shortcut.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # A parsed keyboard shortcut for the docs-search palette — one entry of
+  # DocsKit.configuration.search_shortcuts. A site writes shortcut STRINGS
+  # ("mod+k", "/", "s", "ctrl+shift+f") and this turns each into a key + modifier
+  # set that three places share: the config surface, the server-rendered <kbd>
+  # hint (#label), and the docs-nav matcher (#to_h, serialized to JSON).
+  #
+  #   DocsKit::Shortcut.parse("mod+k").label   # => "Ctrl K"  (JS swaps to "⌘K" on mac)
+  #   DocsKit::Shortcut.parse("mod+k").to_h    # => { "key" => "k", "mod" => true, ... }
+  #
+  # "mod" is the PLATFORM modifier — ⌘ on mac, Ctrl elsewhere — left abstract here
+  # (the server can't know the OS) and resolved in the browser by docs-nav. Use
+  # "mod" for the "primary command" chord so one config works on every platform;
+  # use explicit "ctrl"/"meta" only when you truly mean that physical key.
+  #
+  # Modifier tokens (case-insensitive): mod, ctrl/control, shift, alt/option,
+  # cmd/command/meta. The final token is the key (single char or a named key like
+  # "escape"); a string with no key (e.g. "mod+") is unparseable and yields nil.
+  class Shortcut
+    # Canonical modifier token → the flag it sets.
+    MODIFIER_ALIASES = {
+      "mod" => :mod,
+      "ctrl" => :ctrl, "control" => :ctrl,
+      "shift" => :shift,
+      "alt" => :alt, "option" => :alt,
+      "cmd" => :meta, "command" => :meta, "meta" => :meta
+    }.freeze
+
+    # The order modifiers appear in a #label (matches the common convention).
+    LABEL_ORDER = %i[mod ctrl meta alt shift].freeze
+
+    # Human labels for the modifier flags in a #label. "mod" renders as the
+    # majority default "Ctrl"; docs-nav swaps it to "⌘" on mac.
+    MODIFIER_LABELS = { mod: "Ctrl", ctrl: "Ctrl", meta: "Meta", alt: "Alt", shift: "Shift" }.freeze
+
+    # Parse one shortcut string → a Shortcut, or nil when there's no key to bind.
+    def self.parse(string)
+      tokens = string.to_s.downcase.split("+").map(&:strip).reject(&:empty?)
+      key = tokens.pop
+      return if key.nil? || MODIFIER_ALIASES.key?(key)
+
+      mods = tokens.filter_map { |token| MODIFIER_ALIASES[token] }.to_set
+      new(key, mods)
+    end
+
+    # Parse a list of shortcut strings, dropping any that don't parse.
+    def self.parse_list(strings)
+      Array(strings).filter_map { |string| parse(string) }
+    end
+
+    attr_reader :key
+
+    # key: the final key token (lowercased). mods: a Set of modifier flag symbols.
+    def initialize(key, mods)
+      @key = key
+      @mods = mods
+      freeze
+    end
+
+    def mod? = @mods.include?(:mod)
+    def ctrl? = @mods.include?(:ctrl)
+    def shift? = @mods.include?(:shift)
+    def alt? = @mods.include?(:alt)
+    def meta? = @mods.include?(:meta)
+
+    # The <kbd> badge text: modifiers (in LABEL_ORDER) then the key. In a CHORD
+    # (with a modifier) a single-char key is uppercased for legibility ("mod+k" →
+    # "Ctrl K"); a BARE key is shown exactly as authored ("/", "s"). A named key
+    # (e.g. "escape") is left as-is either way.
+    def label
+      mods = LABEL_ORDER.select { |flag| @mods.include?(flag) }.map { |flag| MODIFIER_LABELS[flag] }.uniq
+      (mods << key_label(chord: !mods.empty?)).join(" ")
+    end
+
+    # The shape docs-nav matches a keydown against (booleans always present so the
+    # JSON is uniform). String keys → clean JSON without symbol quoting.
+    def to_h
+      {
+        "key" => key, "mod" => mod?, "ctrl" => ctrl?,
+        "shift" => shift?, "alt" => alt?, "meta" => meta?
+      }
+    end
+    alias as_json to_h
+
+    def ==(other)
+      other.is_a?(Shortcut) && to_h == other.to_h
+    end
+
+    private
+
+    # The key as it appears in the badge — uppercased only in a chord, and only for
+    # a single char; a named key (length > 1) is always left as authored.
+    def key_label(chord:)
+      chord && key.length == 1 ? key.upcase : key
+    end
+  end
+end

data/lib/docs_kit/templates/new_site.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+# Rails application template for a docs-kit docs site. Run via:
+#
+#   rails new my-docs --minimal -a propshaft -j importmap --skip-... -m new_site.rb
+#
+# or, more simply, via the `docs-kit new` CLI (exe/docs-kit) which supplies the
+# right `rails new` flags. It:
+#   * adds docs-kit + its runtime deps to the Gemfile,
+#   * runs `docs_kit:install` (all the Ruby/CSS/Stimulus wiring),
+#   * syncs the lucide icon set and builds the CSS,
+#   * scaffolds a deployable Kamal setup that calls docs-kit's reusable workflow.
+#
+# The generated app is a complete, deployable standalone docs site.
+
+# --- config the template reads ------------------------------------------------
+# DOCS_KIT_GEM_SOURCE lets the dogfood site (docs-kit/docs) depend on the gem via
+# path: ".." while a real new site depends on the released gem. Default: rubygems.
+gem_source = ENV.fetch("DOCS_KIT_GEM_SOURCE", "") # e.g. 'path: "..", ' or 'github: "mhenrixon/docs-kit", '
+# The GHCR image/service = the OWNER/REPO the site will live in (repo-linked pkg).
+image = ENV.fetch("DOCS_KIT_IMAGE", "mhenrixon/#{app_name}")
+service = ENV.fetch("DOCS_KIT_SERVICE", app_name)
+
+# --- gems ---------------------------------------------------------------------
+gem_line = "gem \"docs-kit\"#{", #{gem_source}" unless gem_source.empty?}"
+inject_into_file "Gemfile", after: %r{source ["']https://rubygems\.org["']\n} do
+  <<~RUBY
+
+    # docs-kit shared docs chrome + its runtime deps
+    #{gem_line}
+    gem "daisyui", require: "daisy_ui"
+    gem "phlex-rails"
+    gem "rails_icons", "~> 1.1"
+    gem "rouge"
+
+    # Optional: expose these docs to AI agents over MCP (a read-only /mcp endpoint).
+    # Uncomment this and the /mcp route in config/routes.rb. See the docs-kit README.
+    # gem "mcp"
+  RUBY
+end
+
+after_bundle do
+  # The whole docs-kit wiring in one call (idempotent).
+  generate "docs_kit:install"
+
+  # Sync the lucide icons the chrome renders, then build the CSS.
+  run "bin/rails g rails_icons:sync --library=lucide --force --quiet"
+  run "bun install --silent" if system("command -v bun >/dev/null 2>&1")
+  run "bun run build:css" if system("command -v bun >/dev/null 2>&1")
+
+  # --- deploy scaffolding (Kamal + the reusable workflow) ---------------------
+  create_file "config/deploy.yml", <<~YAML
+    # Kamal deploy → the oss-infrastructure server (Cloudflare Tunnel + kamal-proxy).
+    # service/image = the repo OWNER/REPO so the ghcr package auto-links to the
+    # repo and GITHUB_TOKEN can push + pull it (no PAT). See docs-kit's README.
+    service: #{service}
+    image: #{image}
+
+    servers:
+      web:
+        hosts:
+          - <%= ENV["DEPLOY_HOST"] %>
+
+    ssh:
+      user: <%= ENV.fetch("DEPLOY_SSH_USER", "oss") %>
+
+    proxy:
+      host: <%= ENV["DEPLOY_DOMAIN"] %>
+      app_port: 3000
+      ssl: false
+      healthcheck:
+        path: /up
+        interval: 5
+        timeout: 30
+
+    registry:
+      server: ghcr.io
+      username: mhenrixon
+      password:
+        - KAMAL_REGISTRY_PASSWORD
+
+    builder:
+      arch: amd64
+      context: .
+      dockerfile: Dockerfile
+
+    env:
+      clear:
+        RAILS_SERVE_STATIC_FILES: "true"
+        RAILS_LOG_TO_STDOUT: "true"
+        # A stateless docs site: SECRET_KEY_BASE only signs cookies, so it's
+        # inlined (no user data at risk). Rotate with `bin/rails secret`.
+        SECRET_KEY_BASE: "#{SecureRandom.hex(64)}"
+  YAML
+
+  create_file ".kamal/secrets", <<~SH
+    # In CI the deploy workflow sets this to the job's GITHUB_TOKEN. Locally,
+    # export it (e.g. KAMAL_REGISTRY_PASSWORD=$(gh auth token)).
+    KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
+  SH
+
+  create_file "Dockerfile", <<~DOCKER
+    # syntax = docker/dockerfile:1
+    ARG RUBY_VERSION=3.4.2
+    FROM ruby:$RUBY_VERSION-slim AS base
+
+    ARG BUN_VERSION=1.3.2
+    ENV BUN_INSTALL="/usr/local/bun"
+    ENV PATH="/usr/local/bun/bin:$PATH"
+    WORKDIR /rails
+    ENV BUNDLE_WITHOUT="development:test" RAILS_ENV="production"
+
+    RUN apt-get update -qq && \\
+        apt-get install --no-install-recommends -y curl libjemalloc2 && \\
+        rm -rf /var/lib/apt/lists /var/cache/apt/archives
+    RUN gem update --system --no-document && gem install -N bundler
+
+    FROM base AS build
+    RUN apt-get update -qq && \\
+        apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config unzip
+    RUN curl -fsSL https://bun.sh/install | bash -s "bun-v${BUN_VERSION}"
+    COPY Gemfile Gemfile.lock ./
+    RUN bundle install && rm -rf ~/.bundle/ "${BUNDLE_PATH}"/ruby/*/cache
+    COPY . .
+    RUN bun install --frozen-lockfile
+    # assets:precompile runs bun run build:css via the css:build rake enhance.
+    RUN SECRET_KEY_BASE_DUMMY=1 ./bin/rails assets:precompile
+
+    FROM base
+    # Kamal verifies this label on --skip-push deploy; must equal `service:`.
+    LABEL service="#{service}"
+    COPY --from=build "${BUNDLE_PATH}" "${BUNDLE_PATH}"
+    COPY --from=build /rails /rails
+    RUN groupadd --system --gid 1000 rails && \\
+        useradd rails --uid 1000 --gid 1000 --create-home --shell /bin/bash && \\
+        chown -R 1000:1000 /rails/log /rails/tmp
+    USER 1000:1000
+    EXPOSE 3000
+    CMD ["./bin/rails", "server", "-b", "0.0.0.0"]
+  DOCKER
+
+  create_file ".github/workflows/deploy-docs.yml", <<~YAML
+    name: Deploy docs
+    # Build + deploy via docs-kit's reusable workflow (defined once for all sites).
+    on:
+      release: { types: [published] }
+      workflow_dispatch:
+    jobs:
+      deploy:
+        uses: mhenrixon/docs-kit/.github/workflows/deploy.yml@main
+        with:
+          image: #{image}
+          service: #{service}
+          build_context: "."
+          dockerfile: "Dockerfile"
+          working_directory: "."
+        secrets: inherit
+  YAML
+
+  create_file "Procfile.dev", <<~PROC
+    web: bin/rails server
+    css: bun run watch:css
+  PROC
+
+  say "\n✅ docs-kit docs site scaffolded.", :green
+  say <<~MSG
+    Next:
+      cd #{app_name}
+      bin/dev                     # or bin/rails server
+    Deploy: push, create a GitHub Release (or run the Deploy docs workflow).
+      Set repo secrets: SSH_PRIVATE_KEY, DEPLOY_HOST, DEPLOY_DOMAIN (env: docs).
+  MSG
+end

data/lib/docs_kit/topbar_link.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # A single external link rendered in the topbar next to the theme switcher —
+  # a repo link, a chat invite, a social profile. Sites declare these in config
+  # as plain Hashes; #topbar_links normalizes each into a TopbarLink so the Shell
+  # stays value-object-driven (like DocsKit::NavItem for the sidebar):
+  #
+  #   c.topbar_links = [
+  #     { href: "https://github.com/me/repo", label: "GitHub",  icon: :github },
+  #     { href: "https://discord.gg/abc",     label: "Discord", icon: :discord },
+  #   ]
+  #
+  # The Shell renders each as an icon-only ghost button; #label is the accessible
+  # name (aria-label + title). #icon is a token DocsUI::BrandMark resolves — a
+  # shipped brand mark (:github, :discord, …) or, failing that, a lucide icon
+  # name (any string DocsUI::Icon knows). nil #icon renders the label as text.
+  TopbarLink = Data.define(:href, :label, :icon) do
+    def initialize(href:, label:, icon: nil)
+      super(href:, label:, icon: icon&.to_sym)
+    end
+
+    # Build a TopbarLink from a Hash (symbol- OR string-keyed, so a YAML/JSON
+    # config loads cleanly) or pass an existing TopbarLink through unchanged.
+    def self.from(link)
+      return link if link.is_a?(self)
+
+      attrs = link.to_h.transform_keys(&:to_sym)
+      new(href: attrs[:href], label: attrs[:label], icon: attrs[:icon])
+    end
+
+    # Whether the href points off-site (absolute http/https). The Shell adds
+    # target=_blank + rel=noopener only for external links; a site-relative link
+    # (e.g. "/changelog") opens in place like any nav link.
+    def external?
+      href.to_s.match?(%r{\Ahttps?://}i)
+    end
+  end
+end

data/lib/docs_kit/version.rb

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

data/lib/docs_kit.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "phlex"
+require "rouge"
+require "zeitwerk"
+
+require_relative "docs_kit/version"
+require_relative "docs_kit/configuration"
+
+# DocsKit — a reusable docs-site component library: the shared Phlex chrome
+# (shell, sidebar, code block, theme switcher, page kit) that lets several docs
+# sites look identical while differing only in configuration.
+#
+# Components live under the `Docs::` namespace and are exposed as a Phlex::Kit,
+# so a host base view can `include Docs` and call `Shell(...)`, `Page(...)`,
+# `Code(...)`, etc., or always use the namespaced `render Docs::Shell.new(...)`.
+module DocsKit
+  class Error < StandardError; end
+
+  class << self
+    # The current configuration, memoized. Reset with DocsKit.reset_configuration!.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+# The DocsUI namespace is a Phlex::Kit so `include DocsUI` exposes every
+# component constant as a bare callable method (DocsUI::Shell(), DocsUI::Code(),
+# ...). Named DocsUI (not Docs) so it never collides with a host app's own
+# `Views::Docs` page namespace, and to match the UI/AdminUI/DocsUI kit convention.
+# Defined before loader.setup so zeitwerk autoloads its children into this
+# already-extended module.
+module DocsUI
+  extend Phlex::Kit
+end
+
+loader = Zeitwerk::Loader.new
+loader.tag = "docs_kit"
+loader.inflector.inflect("docs_kit" => "DocsKit", "docs_ui" => "DocsUI")
+# DocsKit::* support code (registry mixin, engine helpers) under lib/docs_kit/,
+# excluding the eagerly-required files below.
+loader.push_dir(File.expand_path("docs_kit", __dir__), namespace: DocsKit)
+# The shippable Phlex components under app/components/docs_ui/ → DocsUI::*.
+loader.push_dir(File.expand_path("../app/components/docs_ui", __dir__), namespace: DocsUI)
+loader.ignore(File.expand_path("docs_kit/version.rb", __dir__))
+loader.ignore(File.expand_path("docs_kit/configuration.rb", __dir__))
+# docs_kit/rubocop.rb is the RuboCop-cop entry point: it defines cops under
+# RuboCop::Cop::DocsKit::*, not a DocsKit::Rubocop constant, so zeitwerk must not
+# manage it. It (and the cops under lib/rubocop/, which are outside the loader's
+# push_dirs entirely) load only when a `.rubocop.yml` requires "docs_kit/rubocop".
+loader.ignore(File.expand_path("docs_kit/rubocop.rb", __dir__))
+# engine.rb is required explicitly below only under Rails, so zeitwerk never
+# manages it (it would otherwise expect a DocsKit::Engine constant outside Rails).
+loader.ignore(File.expand_path("docs_kit/engine.rb", __dir__))
+# The Rails application template (docs_kit/templates) is executed inside
+# `rails new`, not autoloadable Ruby — ignore it so eager_load! doesn't try to
+# load it (it references template-DSL locals like `app_name`). Generators are
+# loaded by Rails' generator system, not this loader.
+loader.ignore(File.expand_path("docs_kit/templates", __dir__))
+loader.setup
+
+require_relative "docs_kit/engine" if defined?(Rails::Engine)