docs-kit 0.1.0

data/lib/docs_kit/markdown_export/blocks.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module DocsKit
+  class MarkdownExport
+    # The Nokogiri → GFM visitor. Splits into two passes over the bounded kit
+    # vocabulary: block-level elements (this class) produce Markdown lines
+    # separated by blank lines; inline elements (Inline) produce a single run of
+    # text. Unknown block elements recurse into their children (text survives, the
+    # wrapper is dropped), matching the issue's "recurse into children" rule.
+    class Blocks
+      HEADINGS = { "h1" => "#", "h2" => "##", "h3" => "###", "h4" => "####" }.freeze
+      LIST_TAGS = %w[ul ol].freeze
+
+      def initialize(export)
+        @export = export
+        @inline = Inline.new(export)
+      end
+
+      # Render a container's block children, joined by blank lines. Blocks that
+      # yield nothing (whitespace-only text nodes) are dropped so no stray blank
+      # lines accumulate.
+      def render(node)
+        node.children.filter_map { |child| block(child) }
+                     .reject(&:empty?)
+            .join("\n\n")
+      end
+
+      private
+
+      # Dispatch one node to its block rendering. A bare text node contributes its
+      # text only when non-blank (structural whitespace between block tags is
+      # dropped). An unknown element recurses.
+      def block(node)
+        return node.text.strip.empty? ? nil : @inline.render_node(node) if node.text?
+        return nil unless node.element?
+
+        name = node.name
+        return heading(node, HEADINGS[name]) if HEADINGS.key?(name)
+
+        dispatch(node, name)
+      end
+
+      def dispatch(node, name)
+        # A DocsUI::Callout (div[data-md-callout]) becomes a labelled blockquote —
+        # checked BEFORE the structural-div recurse so it isn't flattened away.
+        level = node["data-md-callout"]
+        return callout(node, level) if level
+
+        block_element(node, name)
+      end
+
+      def block_element(node, name)
+        case name
+        when "p" then paragraph(node)
+        when "pre" then code_fence(node)
+        when "ul", "ol" then list(node, ordered: name == "ol")
+        when "table" then Table.new(@export).render(node)
+        when "blockquote" then blockquote(node)
+        else leaf(node, name) # hr/img, else recurse into an unknown wrapper
+        end
+      end
+
+      # The self-contained leaf blocks; anything else is a structural wrapper
+      # (section/header/div/…) whose children carry the content, so recurse.
+      def leaf(node, name)
+        case name
+        when "hr" then "---"
+        when "img" then @inline.image(node)
+        else render(node)
+        end
+      end
+
+      # A heading's text. DocsUI::Section wraps its title in a self-referencing
+      # anchor (a deep-link affordance) with a decorative "#" span; both are
+      # chrome, so render the heading's inner TEXT rather than a `[Title](#id)`
+      # link. The Inline pass already drops the "#" span.
+      def heading(node, hashes)
+        "#{hashes} #{@inline.heading_text(node)}"
+      end
+
+      def paragraph(node)
+        @inline.render(node)
+      end
+
+      # A DocsUI::Code block is pre inside div[data-md-lang]; the fence carries
+      # that resolved language (blank for plaintext → a language-less fence). The
+      # source is the <pre>'s text, un-escaped (Nokogiri already decoded entities).
+      def code_fence(node)
+        lang = fence_language(node)
+        source = node.text.delete_suffix("\n")
+        "```#{lang}\n#{source}\n```"
+      end
+
+      # The language is on the DocsUI::Code wrapper (div[data-md-lang]) around the
+      # <pre>. "plaintext" (or absent) means no language token on the fence.
+      def fence_language(node)
+        lang = node.ancestors("[data-md-lang]").first&.[]("data-md-lang").to_s
+        lang == "plaintext" ? "" : lang
+      end
+
+      # A blockquote's block children, each line prefixed "> ".
+      def blockquote(node)
+        quote(render(node))
+      end
+
+      # A callout → `> **Label:** body` as a blockquote. Callout stamps a
+      # `div.font-semibold` title (present only when title: is given) and a
+      # `div.text-sm` body. Read them separately: the author's title is the label
+      # when present (else the level label), and only the body div is rendered so
+      # the title never fuses into the body text.
+      def callout(node, level)
+        title = node.at_css(".font-semibold")
+        body_node = node.at_css(".text-sm") || node
+        label = title ? @inline.render(title).strip : CALLOUT_LABELS.fetch(level, "Note")
+        body = @inline.render(body_node).strip
+        quote("**#{label}:** #{body}")
+      end
+
+      def quote(text)
+        text.split("\n").map { |line| line.empty? ? ">" : "> #{line}" }.join("\n")
+      end
+
+      # A list, rendered at the given indent depth. Each item is a marker (- or
+      # 1./2./…) plus its inline text; nested lists indent two spaces per level.
+      def list(node, ordered:, depth: 0)
+        index = 0
+        items(node).map do |li|
+          index += 1
+          marker = ordered ? "#{index}. " : "- "
+          "#{'  ' * depth}#{marker}#{item(li, depth)}"
+        end.join("\n")
+      end
+
+      def items(node)
+        node.children.select { |child| child.element? && child.name == "li" }
+      end
+
+      # An <li>'s content: its inline text, plus any nested list indented one level
+      # deeper on following lines.
+      def item(node, depth)
+        text = @inline.render(inline_children(node)).strip
+        nested = node.children.filter_map do |child|
+          next unless list?(child)
+
+          "\n#{list(child, ordered: child.name == 'ol', depth: depth + 1)}"
+        end
+        "#{text}#{nested.join}"
+      end
+
+      # The li's children minus nested lists (those render on their own lines).
+      def inline_children(node)
+        node.children.reject { |child| list?(child) }
+      end
+
+      def list?(node)
+        node.element? && LIST_TAGS.include?(node.name)
+      end
+    end
+  end
+end

data/lib/docs_kit/markdown_export/inline.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module DocsKit
+  class MarkdownExport
+    # The inline pass: a node's descendants flattened to a single run of Markdown
+    # text (bold/italic/code/links). Block elements never reach here; an unknown
+    # inline element recurses into its children so its text survives.
+    class Inline
+      # Emphasis tags whose Markdown just wraps the inner text in a delimiter.
+      # Keeps #render_node a flat dispatch instead of a branch per tag.
+      WRAP = {
+        "strong" => "**", "b" => "**",
+        "em" => "*", "i" => "*",
+        "del" => "~~", "s" => "~~"
+      }.freeze
+
+      def initialize(export)
+        @export = export
+      end
+
+      # Inline-render a node OR a Nokogiri node-set (an <li>'s inline children).
+      def render(node_or_set)
+        nodes = node_or_set.respond_to?(:children) ? node_or_set.children : node_or_set
+        nodes.map { |child| render_node(child) }.join
+      end
+
+      # Dispatch one node. Text is returned verbatim (Nokogiri decoded entities,
+      # so `<`/`&` are literal — GFM keeps them). Elements map to their inline
+      # Markdown; the DocsUI::Section hover-anchor "#" span is dropped.
+      def render_node(node)
+        return node.text if node.text?
+        return "" unless node.element?
+
+        name = node.name
+        wrap = WRAP[name]
+        return "#{wrap}#{render(node)}#{wrap}" if wrap
+
+        element(node, name)
+      end
+
+      # The non-emphasis inline elements. `code` keeps its text verbatim; `a`
+      # becomes a link; a decorative "#" span (Section's hover anchor) is dropped;
+      # any other wrapper recurses so its text survives.
+      def element(node, name)
+        case name
+        when "code" then code_span(node.text)
+        when "a" then link(node)
+        when "img" then image(node)
+        when "br" then "  \n"
+        when "span" then anchor_decoration?(node) ? "" : render(node)
+        else render(node)
+        end
+      end
+
+      def image(node)
+        "![#{node['alt']}](#{@export.absolutize(node['src'])})"
+      end
+
+      # A heading's inline text, treating a self-referencing anchor (href="#id",
+      # DocsUI::Section's deep-link wrapper) as transparent — its children render
+      # directly, so a heading is `## Title`, never `## [Title](#id)`.
+      def heading_text(node)
+        node.children.map do |child|
+          self_anchor?(child) ? render(child) : render_node(child)
+        end.join.strip
+      end
+
+      private
+
+      # A GFM-correct inline code span. The fence is a backtick run one longer
+      # than the longest run inside the text, so an interior backtick can never
+      # close the span; a space pads content that starts or ends with a backtick.
+      def code_span(text)
+        fence = "`" * ((text.scan(/`+/).map(&:length).max || 0) + 1)
+        pad = text.start_with?("`") || text.end_with?("`") ? " " : ""
+        "#{fence}#{pad}#{text}#{pad}#{fence}"
+      end
+
+      def self_anchor?(node)
+        node.element? && node.name == "a" && node["href"].to_s.start_with?("#")
+      end
+
+      def link(node)
+        "[#{render(node)}](#{@export.absolutize(node['href'])})"
+      end
+
+      # DocsUI::Section renders a decorative "#" span (a hover deep-link glyph)
+      # inside its heading anchor. It's chrome, not content — drop it so a heading
+      # doesn't export as "Title #".
+      def anchor_decoration?(node)
+        node.text.strip == "#" && node.parent&.name == "a"
+      end
+    end
+  end
+end

data/lib/docs_kit/markdown_export/table.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module DocsKit
+  class MarkdownExport
+    # A GFM pipe table. The first row (thead, or the first row if there's no
+    # thead) is the header; a separator row follows; the rest are body rows. Cell
+    # content is inline Markdown with pipes escaped so they don't break the table.
+    class Table
+      def initialize(export)
+        @inline = Inline.new(export)
+      end
+
+      def render(node)
+        rows = rows(node)
+        return "" if rows.empty?
+
+        width = rows.map(&:length).max
+        header, *body = pad(rows, width)
+        lines = [row(header), separator(width)]
+        lines.concat(body.map { |cells| row(cells) })
+        lines.join("\n")
+      end
+
+      private
+
+      # Pad every row out to +width+ with empty cells so the header, separator,
+      # and all body rows declare the same column count (a rectangular GFM table).
+      def pad(rows, width)
+        rows.map { |cells| cells + Array.new(width - cells.length, "") }
+      end
+
+      # All rows as arrays of cell strings, header row first. A <thead> row leads;
+      # <tbody>/bare <tr> rows follow.
+      def rows(node)
+        node.css("tr").map do |tr|
+          tr.css("th, td").map { |cell| cell_text(cell) }
+        end
+      end
+
+      def cell_text(cell)
+        @inline.render(cell).strip.gsub("|", "\\|").tr("\n", " ")
+      end
+
+      def row(cells)
+        "| #{cells.join(' | ')} |"
+      end
+
+      def separator(count)
+        "| #{Array.new(count, '---').join(' | ')} |"
+      end
+    end
+  end
+end

data/lib/docs_kit/markdown_export.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module DocsKit
+  # Derives a faithful GFM Markdown twin of a docs page FROM the page's own
+  # rendered HTML. The gem emits the HTML, so the tag vocabulary is bounded and a
+  # small hand-rolled Nokogiri visitor converts it exactly — no dependence on
+  # authoring style (Phlex, `md` islands, and raw tags in Prose all convert
+  # identically because conversion happens post-render).
+  #
+  #   DocsKit::MarkdownExport.new(page_view, view_context:, base_url: req.base_url).to_md
+  #
+  # The page is rendered, the #docs-content region (DocsUI::Shell's anchor) is
+  # extracted, [data-md-skip] chrome is stripped, and the remaining subtree is
+  # walked to Markdown. Data hints the kit stamps at render time drive the tricky
+  # cases: data-md-lang (DocsUI::Code) → a ```lang fence; data-md-callout
+  # (DocsUI::Callout) → a `> **Tip:**` blockquote.
+  class MarkdownExport
+    # The extraction anchor DocsUI::Shell stamps on its content column.
+    CONTENT_SELECTOR = "#docs-content"
+
+    # Elements dropped whole — chrome and non-content that must never reach the
+    # Markdown twin. [data-md-skip] is authored (Page's "← Home" nav); script and
+    # style carry no readable content.
+    DROP_SELECTOR = "[data-md-skip], script, style"
+
+    # Callout level → the bold label opening its blockquote.
+    CALLOUT_LABELS = { "note" => "Note", "tip" => "Tip", "warning" => "Warning" }.freeze
+
+    # The parameter kinds that count as a keyword arg (required or optional) when
+    # sniffing whether a view's #call accepts a view_context: kwarg.
+    KEYWORD_PARAM_TYPES = %i[key keyreq].freeze
+
+    # view: a renderable page (a Phlex component in production). view_context: the
+    # Rails view context to render it through (CSRF, url helpers). base_url: the
+    # request's base URL, used to absolutize relative link/image hrefs so the
+    # exported Markdown is portable.
+    def initialize(view, view_context: nil, base_url: nil)
+      @view = view
+      @view_context = view_context
+      @base_url = base_url
+    end
+
+    # The page's content as GFM Markdown, or "" when there is no #docs-content
+    # region (a page that isn't the docs chrome — the HTML route is untouched).
+    def to_md
+      content = extract_content
+      return "" unless content
+
+      content.search(DROP_SELECTOR).each(&:remove)
+      Blocks.new(self).render(content).strip
+    end
+
+    # Absolutize a relative href/src against the base URL; leave absolute and
+    # anchor/mailto links untouched. No base URL → return as-is.
+    def absolutize(url)
+      return url if url.nil? || url.empty?
+      return url unless @base_url
+      return url if url.match?(%r{\A(?:[a-z][a-z0-9+.-]*:|//|#)}i)
+
+      "#{@base_url.chomp('/')}/#{url.delete_prefix('/')}"
+    end
+
+    private
+
+    # Render the page to an HTML document and grab the #docs-content subtree.
+    def extract_content
+      Nokogiri::HTML5.fragment(render_html).at_css(CONTENT_SELECTOR)
+    end
+
+    # Render the page to an HTML string. Production renders a Phlex component
+    # through the Rails view context (so url helpers/CSRF work); in isolation the
+    # view is rendered via #call. The seam: a view whose #call accepts a
+    # view_context: kwarg gets it; a Phlex component with a view_context is
+    # rendered through Rails; otherwise a bare #call.
+    def render_html
+      if call_accepts_view_context?
+        @view.call(view_context: @view_context)
+      elsif @view_context && @view.respond_to?(:render_in)
+        @view_context.render(@view)
+      else
+        @view.call
+      end
+    end
+
+    def call_accepts_view_context?
+      @view.respond_to?(:call) &&
+        @view.method(:call).parameters.any? { |type, name| name == :view_context && KEYWORD_PARAM_TYPES.include?(type) }
+    end
+  end
+end

data/lib/docs_kit/mcp_server.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DocsKit
+  # Builds the read-only MCP::Server a docs-kit site exposes at POST /mcp — a
+  # stateless JSON-RPC skin over DocsKit::McpTools, so an agent (Claude Code,
+  # Claude.ai, Cursor) adds one URL and the docs become first-class tools:
+  #
+  #   server = DocsKit::McpServer.build(DocsKit.configuration, base_url:, view_context:)
+  #   server.handle_json(request.body.read)   # → the JSON-RPC response string
+  #
+  # The `mcp` gem is OPTIONAL and runtime-detected (docs-kit depends on it in no
+  # gemspec list). .build returns nil when the gem is absent, and the controller
+  # only reaches here when DocsKit.configuration#mcp_enabled? — so a site without
+  # the gem, or with c.mcp = false, is byte-identical to before this feature.
+  #
+  # base_url + view_context ride in the server_context (the SDK threads it to
+  # every tool block), so the tools render each page's Markdown twin through the
+  # Rails view context and absolutize URLs — the same seam LlmsController#full
+  # uses. The three tools mirror DocsKit::McpTools one-to-one.
+  module McpServer
+    module_function
+
+    # The MCP::Server for this config, or nil when the `mcp` gem isn't loadable.
+    # base_url/view_context flow to the tools via server_context.
+    def build(config, base_url: nil, view_context: nil)
+      return unless mcp_available?
+
+      server = MCP::Server.new(
+        name: config.brand.to_s,
+        version: DocsKit::VERSION,
+        instructions: instructions_for(config, base_url),
+        server_context: { config:, base_url:, view_context: }
+      )
+      define_tools(server)
+      server
+    end
+
+    # Whether the official MCP SDK is loadable — the runtime-detection gate. Kept
+    # as a seam so specs can force the gem-absent branch without unloading it.
+    def mcp_available?
+      require "mcp"
+      defined?(::MCP::Server) ? true : false
+    rescue LoadError
+      false
+    end
+
+    # Server instructions: the site's tagline (when set) plus a pointer to
+    # /llms.txt, so an agent knows what these docs cover and where the full index
+    # lives. base_url absolutizes the /llms.txt hint when available.
+    def instructions_for(config, base_url)
+      llms = base_url ? "#{base_url.chomp('/')}/llms.txt" : "/llms.txt"
+      lines = []
+      tagline = config.tagline
+      lines << tagline.to_s if tagline && !tagline.to_s.empty?
+      lines << "Read-only documentation tools for #{config.brand}. " \
+               "Use search_docs to find sections, get_page to read a page's Markdown, " \
+               "and list_pages to enumerate the docs. Full index: #{llms}."
+      lines.join(" ")
+    end
+
+    # Register the three read-only tools. Each block pulls config + render context
+    # from server_context, calls the matching DocsKit::McpTools function, and
+    # returns the result as pretty JSON text (agents consume structured data).
+    def define_tools(server)
+      define_list_pages(server)
+      define_get_page(server)
+      define_search_docs(server)
+    end
+
+    def define_list_pages(server)
+      server.define_tool(
+        name: "list_pages",
+        description: "List every documentation page: its slug, title, group, and URL. " \
+                     "Use the slug with get_page.",
+        input_schema: { type: "object", properties: {}, required: [] }
+      ) do |server_context:|
+        cfg = server_context[:config]
+        McpServer.json_response(McpTools.list_pages(cfg, base_url: server_context[:base_url]))
+      end
+    end
+
+    def define_get_page(server)
+      server.define_tool(
+        name: "get_page",
+        description: "Fetch one documentation page as Markdown, by its slug (see list_pages). " \
+                     "Returns the page's full Markdown twin.",
+        input_schema: {
+          type: "object",
+          properties: { slug: { type: "string", description: "The page slug, e.g. \"installation\"." } },
+          required: ["slug"]
+        }
+      ) do |slug:, server_context:|
+        cfg = server_context[:config]
+        McpServer.json_response(
+          McpTools.get_page(cfg, slug:, base_url: server_context[:base_url],
+                                 view_context: server_context[:view_context])
+        )
+      end
+    end
+
+    def define_search_docs(server)
+      server.define_tool(
+        name: "search_docs",
+        description: "Full-text search across all documentation pages. " \
+                     "Returns ranked hits with the page, section, URL, and a snippet.",
+        input_schema: {
+          type: "object",
+          properties: { query: { type: "string", description: "The search terms." } },
+          required: ["query"]
+        }
+      ) do |query:, server_context:|
+        cfg = server_context[:config]
+        McpServer.json_response(
+          McpTools.search_docs(cfg, query:, base_url: server_context[:base_url],
+                                    view_context: server_context[:view_context])
+        )
+      end
+    end
+
+    # Wrap a Ruby data payload as a single-text MCP tool response, the data as
+    # pretty JSON so an agent parses structured fields (not prose).
+    def json_response(payload)
+      MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(payload) }])
+    end
+  end
+end

data/lib/docs_kit/mcp_tools.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module DocsKit
+  # The pure, HTTP-free core the built-in MCP server exposes — three plain-Ruby
+  # functions over the SAME registry, Markdown twins, and search index the docs
+  # already render from, so an agent queries live docs, never a stale scrape:
+  #
+  #   list_pages(config)         → [{ slug, title, group, url }]           authored pages only
+  #   get_page(config, slug:)    → { found:, title:, url:, markdown: } | { found: false, message: }
+  #   search_docs(config, query:)→ [{ page_title, section_title, url, snippet }]  ranked
+  #
+  # Zero `mcp`-gem dependency and zero JSON-RPC: DocsKit::McpServer wraps these
+  # into MCP tools, and the controller only threads the Rails view context (for
+  # url helpers/CSRF, the same seam DocsKit::LlmsController#full uses). So the
+  # whole consumption story is unit-testable without booting Rails or the SDK.
+  #
+  # "Authored" means a resolvable #view_class — DocsKit::LlmsText.pages already
+  # flattens every registry to just those, so an unwritten page is never listed,
+  # fetched, or indexed (no dead links, no 404s over the protocol).
+  module McpTools
+    module_function
+
+    # The authored pages across every registry, in config/registry order, as a
+    # flat list of { slug, title, group, url } — url absolutized against base_url
+    # when given (agents fetch a portable URL), else the root-relative href.
+    def list_pages(config, base_url: nil)
+      LlmsText.pages(config).map do |page|
+        {
+          slug: page.slug,
+          title: page.title,
+          group: page.group,
+          url: absolutize(page.href, base_url)
+        }
+      end
+    end
+
+    # A single page's Markdown twin by slug. Renders the page's #view_class
+    # through view_context (nil off-Rails) exactly as LlmsController#full does. An
+    # unknown or unwritten slug returns { found: false } with a message listing
+    # the valid slugs, so an agent can correct itself instead of hitting an error.
+    def get_page(config, slug:, base_url: nil, view_context: nil)
+      page = find_page(config, slug)
+      return not_found(config, slug) unless page
+
+      {
+        found: true,
+        slug: page.slug,
+        title: page.title,
+        url: absolutize(page.href, base_url),
+        markdown: render_markdown(page, base_url:, view_context:)
+      }
+    end
+
+    # The top DocsKit::SearchIndex hits for query, as { page_title, section_title,
+    # url, snippet } — url absolutized, snippet reduced to plain text (the index's
+    # HTML <mark> highlight stripped, since MCP delivers text, not HTML). Blank
+    # query → []. Builds the index from the same twins search + llms-full serve.
+    def search_docs(config, query:, base_url: nil, view_context: nil)
+      index_for(config, base_url:, view_context:).search(query).map do |hit|
+        {
+          page_title: hit.page_title,
+          section_title: hit.section_title,
+          url: absolutize(hit.href, base_url),
+          snippet: strip_html(hit.snippet)
+        }
+      end
+    end
+
+    # The authored page with this slug across every registry, or nil (an unwritten
+    # page has no resolvable view_class, so it's absent from LlmsText.pages).
+    def find_page(config, slug)
+      LlmsText.pages(config).find { |page| page.slug.to_s == slug.to_s }
+    end
+
+    # A { found: false } result whose message names every valid slug, so an agent
+    # that guessed wrong can retry with a real one.
+    def not_found(config, slug)
+      valid = list_pages(config).map { |page| page[:slug] }
+      {
+        found: false,
+        slug: slug,
+        message: "No page with slug #{slug.inspect}. Valid slugs: #{valid.join(', ')}."
+      }
+    end
+
+    # A page's GFM Markdown twin, rendered through the view context so url helpers
+    # and relative-link absolutization resolve — the LlmsController#full seam.
+    def render_markdown(page, base_url:, view_context:)
+      MarkdownExport.new(page.view_class.new, view_context:, base_url:).to_md
+    end
+
+    # A DocsKit::SearchIndex over every authored page's twin — the same triples
+    # DocsKit::SearchController builds, so MCP search can't drift from the pages.
+    def index_for(config, base_url:, view_context:)
+      triples = LlmsText.pages(config).map do |page|
+        [page.title, page.href, render_markdown(page, base_url:, view_context:)]
+      end
+      SearchIndex.new(triples)
+    end
+
+    # href absolutized against base_url (no .md suffix — MCP serves the page URL,
+    # not the twin). Relative href when base_url is nil. Mirrors LlmsText.md_url.
+    def absolutize(href, base_url)
+      return href unless base_url
+
+      "#{base_url.chomp('/')}#{href}"
+    end
+
+    # Reduce the search index's HTML-safe snippet (term wrapped in <mark>, rest
+    # CGI-escaped) to plain text: drop the <mark> tags and unescape entities, so
+    # the MCP snippet is human/agent-readable text rather than HTML.
+    def strip_html(snippet)
+      CGI.unescapeHTML(snippet.to_s.gsub(%r{</?mark>}, ""))
+    end
+  end
+end

data/lib/docs_kit/nav_item.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DocsKit
+  # A single sidebar link. Sites map their own registries (Doc, Demo,
+  # ComponentDoc, ...) to NavItems in the nav callable, so the Sidebar stays
+  # registry-agnostic:
+  #
+  #   c.nav = -> {
+  #     {
+  #       "Demos" => Demo.grouped.transform_values { |demos|
+  #         demos.map { |d| DocsKit::NavItem.new(href: demo_path(d.slug), label: d.title, icon: d.icon) }
+  #       },
+  #     }
+  #   }
+  #
+  # The Sidebar renders #label at #href, with an optional lucide #icon.
+  NavItem = Data.define(:href, :label, :icon) do
+    def initialize(href:, label:, icon: nil)
+      super
+    end
+  end
+end