RubyGems - docs-kit - Versions diffs - 0.1.0 - Mend

docs-kit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (89) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +46 -0
data/LICENSE.txt +21 -0
data/README.md +939 -0
data/app/components/docs_ui/brand_mark.rb +88 -0
data/app/components/docs_ui/callout.rb +37 -0
data/app/components/docs_ui/code.rb +123 -0
data/app/components/docs_ui/endpoint.rb +44 -0
data/app/components/docs_ui/error_table.rb +72 -0
data/app/components/docs_ui/example.rb +102 -0
data/app/components/docs_ui/field_table.rb +46 -0
data/app/components/docs_ui/header.rb +30 -0
data/app/components/docs_ui/icon.rb +65 -0
data/app/components/docs_ui/json_response.rb +46 -0
data/app/components/docs_ui/markdown.rb +187 -0
data/app/components/docs_ui/markdown_action.rb +45 -0
data/app/components/docs_ui/on_this_page.rb +104 -0
data/app/components/docs_ui/open_api_operation.rb +126 -0
data/app/components/docs_ui/page.rb +83 -0
data/app/components/docs_ui/page_helpers.rb +52 -0
data/app/components/docs_ui/prop_table.rb +43 -0
data/app/components/docs_ui/prose.rb +30 -0
data/app/components/docs_ui/request_example.rb +85 -0
data/app/components/docs_ui/search_box.rb +106 -0
data/app/components/docs_ui/search_results.rb +95 -0
data/app/components/docs_ui/section.rb +94 -0
data/app/components/docs_ui/shell.rb +161 -0
data/app/components/docs_ui/sidebar.rb +106 -0
data/app/components/docs_ui/table.rb +64 -0
data/app/components/docs_ui/theme_switcher.rb +46 -0
data/app/components/docs_ui/topbar_links.rb +42 -0
data/app/controllers/docs_kit/llms_controller.rb +76 -0
data/app/controllers/docs_kit/mcp_controller.rb +60 -0
data/app/controllers/docs_kit/search_controller.rb +72 -0
data/app/javascript/docs_kit/controllers/docs_nav_controller.js +619 -0
data/config/importmap.rb +15 -0
data/config/rubocop/docs_kit.yml +24 -0
data/exe/docs-kit +80 -0
data/lib/docs-kit.rb +5 -0
data/lib/docs_kit/api_client.rb +52 -0
data/lib/docs_kit/api_request.rb +66 -0
data/lib/docs_kit/api_templates.rb +92 -0
data/lib/docs_kit/configuration.rb +485 -0
data/lib/docs_kit/controller.rb +47 -0
data/lib/docs_kit/engine.rb +49 -0
data/lib/docs_kit/llms_text.rb +105 -0
data/lib/docs_kit/markdown_export/blocks.rb +160 -0
data/lib/docs_kit/markdown_export/inline.rb +95 -0
data/lib/docs_kit/markdown_export/table.rb +53 -0
data/lib/docs_kit/markdown_export.rb +92 -0
data/lib/docs_kit/mcp_server.rb +128 -0
data/lib/docs_kit/mcp_tools.rb +118 -0
data/lib/docs_kit/nav_item.rb +22 -0
data/lib/docs_kit/open_api/document.rb +91 -0
data/lib/docs_kit/open_api/operation.rb +213 -0
data/lib/docs_kit/open_api/schema.rb +178 -0
data/lib/docs_kit/open_api.rb +55 -0
data/lib/docs_kit/registry.rb +152 -0
data/lib/docs_kit/rubocop.rb +19 -0
data/lib/docs_kit/search_hit.rb +28 -0
data/lib/docs_kit/search_index/snippet.rb +65 -0
data/lib/docs_kit/search_index.rb +169 -0
data/lib/docs_kit/shortcut.rb +99 -0
data/lib/docs_kit/templates/new_site.rb +175 -0
data/lib/docs_kit/topbar_link.rb +39 -0
data/lib/docs_kit/version.rb +5 -0
data/lib/docs_kit.rb +72 -0
data/lib/generators/docs_kit/install/USAGE +15 -0
data/lib/generators/docs_kit/install/install_generator.rb +447 -0
data/lib/generators/docs_kit/install/sync_report.rb +64 -0
data/lib/generators/docs_kit/install/templates/agents_md.erb +105 -0
data/lib/generators/docs_kit/install/templates/application.tailwind.css.erb +39 -0
data/lib/generators/docs_kit/install/templates/build-css +34 -0
data/lib/generators/docs_kit/install/templates/build_css.rake +13 -0
data/lib/generators/docs_kit/install/templates/doc.rb.erb +17 -0
data/lib/generators/docs_kit/install/templates/docs_controller.rb.erb +14 -0
data/lib/generators/docs_kit/install/templates/docs_kit.rb.erb +91 -0
data/lib/generators/docs_kit/install/templates/installation_page.rb.erb +37 -0
data/lib/generators/docs_kit/install/templates/landing.rb.erb +25 -0
data/lib/generators/docs_kit/install/templates/landings_controller.rb.erb +7 -0
data/lib/generators/docs_kit/install/templates/phlex.rb.erb +14 -0
data/lib/generators/docs_kit/install/templates/rails_icons.rb.erb +12 -0
data/lib/generators/docs_kit/install/templates/skill.md.erb +88 -0
data/lib/generators/docs_kit/page/USAGE +26 -0
data/lib/generators/docs_kit/page/page_generator.rb +127 -0
data/lib/generators/docs_kit/page/templates/page.rb.erb +21 -0
data/lib/rubocop/cop/docs_kit/escaped_interpolation_in_heredoc.rb +119 -0
data/lib/rubocop/cop/docs_kit/render_component_preferred.rb +123 -0
metadata +253 -0

data/lib/docs_kit/configuration.rb ADDED Viewed

@@ -0,0 +1,485 @@
+# frozen_string_literal: true
+module DocsKit
+  # Per-site configuration for the shared docs chrome. Everything that differs
+  # between two otherwise-identical docs sites lives here, so the Phlex shell
+  # (DocsUI::Shell, DocsUI::Sidebar, DocsUI::ThemeSwitcher) is byte-identical across
+  # sites and only the config changes.
+  #
+  #   DocsKit.configure do |c|
+  #     c.brand        = "phlex-reactive"
+  #     c.title_suffix = "phlex-reactive"
+  #     c.themes       = %w[dark light synthwave ...]
+  #     c.nav          = -> { { "Demos" => Demo.grouped, "Docs" => Doc.grouped } }
+  #   end
+  class Configuration
+    # The brand text shown in the topbar and sidebar header.
+    attr_accessor :brand
+    # A one-line site summary, rendered as the llms.txt blockquote
+    # (`> {tagline}`) under the H1. Defaults to nil → the blockquote line is
+    # omitted, so a site that never sets it still gets a valid llms.txt. Purely
+    # for the AI-readable index (DocsKit::LlmsText); the chrome never shows it.
+    attr_accessor :tagline
+    # The href the topbar brand link points at. Defaults to "/" (site root). A
+    # site whose docs live under a subpath sets its own (e.g. "/docs") so the
+    # brand link is a one-line config change, not a Shell subclass.
+    attr_accessor :brand_href
+    # Appended to a page's <title> (e.g. "Installation · phlex-reactive").
+    # Defaults to #brand when unset.
+    attr_writer :title_suffix
+    # The themes offered by the ThemeSwitcher. The first is the page default
+    # unless #default_theme is set. Must match the themes enabled in the
+    # site's Tailwind @plugin "daisyui" { themes: ... } block.
+    attr_accessor :themes
+    # The data-theme applied to <html> on first paint. Defaults to the first
+    # entry of #themes.
+    attr_writer :default_theme
+    # A callable returning the sidebar nav as an ordered Hash of
+    # { "Heading" => { "Subgroup" => [items] } }. Each item must respond to
+    # the duck type the Sidebar renders (see DocsUI::Sidebar#nav_link): #href,
+    # #label, and optional #icon. Defaults to an empty nav.
+    #
+    # Prefer #nav_registries for the common case — an explicit #nav lambda is
+    # only needed for bespoke nav (multiple registries interleaved, custom
+    # subgroups). When #nav is left at its default, the sidebar derives from
+    # #nav_registries instead.
+    attr_reader :nav
+    # Assigning #nav marks it explicit, so #nav_groups uses it verbatim rather
+    # than deriving from #nav_registries — tracked by a flag, not object
+    # identity, so ANY assigned lambda wins (even one that resolves to {}).
+    def nav=(value)
+      @nav_explicit = true
+      @nav = value
+    end
+    # An ordered { "Heading" => registry_class } map. Each registry responds to
+    # .nav_items (Registry v2) → { group => [NavItem] } for its authored pages.
+    # #nav_groups derives the whole sidebar from this with zero site code, so a
+    # site never hand-writes the nav lambda. Defaults to {}. An explicit #nav
+    # lambda still wins (full backwards compatibility).
+    attr_accessor :nav_registries
+    # Optional callable returning a short version-badge string for the sidebar
+    # header (e.g. -> { "v#{DaisyUI::VERSION}" }). nil renders no badge.
+    attr_accessor :version_badge
+    # The stylesheet logical names linked in <head>, in order. Defaults to
+    # ["application"] (the Bun/Tailwind-compiled build). A site that ships extra
+    # stylesheets (e.g. a separate rouge theme) lists them here.
+    attr_accessor :stylesheets
+    # The Rouge theme class used by DocsUI::Code for inline syntax-highlight CSS.
+    # This is the BASE (light) theme, emitted un-scoped so it applies to every
+    # theme unless a dark override wins (see #code_theme_dark).
+    attr_accessor :code_theme
+    # An optional second Rouge theme (String name or Class) used for the site's
+    # DARK daisyUI themes. Default nil → single-theme behavior, fully backwards
+    # compatible. When set, DocsUI::Code additionally emits this theme's CSS scoped
+    # under [data-theme=X] .code-highlight for each shipped dark theme (see
+    # #dark_themes), so code blocks stay readable when the switcher flips to a
+    # dark theme — CSS-only, no JS, no flash.
+    attr_accessor :code_theme_dark
+    # The theme names treated as DARK for #code_theme_dark scoping. Defaults to
+    # the built-in daisyUI dark themes (DEFAULT_DARK_THEMES). Intersected with
+    # #themes at render time (see #dark_themes_shipped) so only shipped themes
+    # generate CSS. Override to name custom dark themes (e.g. %w[zazu-dark]).
+    attr_accessor :dark_themes
+    # The lucide icon name used for a nav group with no explicit icon.
+    attr_accessor :default_group_icon
+    # The RailsIcons library docs-kit renders its OWN chrome icons from (the
+    # sidebar carets, search glyph, theme toggle, etc.). Defaults to "lucide" to
+    # match the lucide icon names docs-kit ships. This is independent of the host
+    # app's RailsIcons.configuration.default_library — a host whose default is
+    # phosphor/heroicons can leave this at "lucide" so the chrome keeps rendering,
+    # without flipping its global default. Set to nil to defer to the host's
+    # default_library.
+    attr_accessor :icon_library
+    # Namespaces the sidebar's localStorage keys (collapse state) so two docs
+    # sites on the same origin don't clobber each other. Defaults to a slug of
+    # the brand.
+    attr_writer :nav_storage_key
+    # The default "On this page" (auto-TOC) placement, used by DocsUI::Page when a
+    # page doesn't pass its own on_page:. One of the ON_PAGE_MODES, or false to
+    # render no auto-TOC by default.
+    attr_writer :on_page_default
+    # Friendly-name → Rouge lexer aliases for code blocks, merged over the
+    # built-in defaults. Any language Rouge knows (~200) already works by its own
+    # name/alias; use this only to add or override (e.g. { curl: "console",
+    # dockerfile: "docker" }). Value is anything Rouge::Lexer.find accepts.
+    attr_accessor :code_lexer_aliases
+    # The lexer used when a requested language can't be resolved. Default
+    # "plaintext" (no highlighting, never raises).
+    attr_accessor :code_lexer_fallback
+    # Human labels for language tabs in DocsUI::Example, merged over the built-ins
+    # (e.g. { elixir: "Elixir", curl: "cURL" }). Unknown tokens humanize.
+    attr_accessor :code_language_labels
+    # Whether DocsUI::Page shows the "Markdown" masthead action — a link to the
+    # page's `.md` twin that docs-nav enhances into copy-to-clipboard. Defaults to
+    # true; set false to hide the affordance site-wide (the `.md` route still
+    # works). See DocsKit::MarkdownExport / DocsKit::Controller#render_page.
+    attr_accessor :page_markdown_action
+    # Whether the built-in read-only MCP endpoint (DocsKit::McpController, a
+    # POST /mcp JSON-RPC server exposing list_pages / get_page / search_docs over
+    # the same registry the docs render from) is active. Defaults to true, but the
+    # endpoint only turns on when the optional `mcp` gem is ALSO present and the
+    # host draws the route — #mcp_enabled? gates on both. Set false to keep the
+    # endpoint off even on a site that bundles the gem. See DocsKit::McpServer.
+    attr_accessor :mcp
+    # Whether the topbar renders the docs-search form (and the docs-nav palette
+    # markup). Defaults to true. Set false to hide search site-wide — the route
+    # can stay drawn, but no affordance points at it. Gated together with a
+    # present #search_path by #search_enabled?, which the Shell reads.
+    attr_accessor :search
+    # The path the topbar search form submits to (GET ?q=), and the base the
+    # palette fetches `.json` from. Defaults to "/docs/search" — the route the
+    # install generator draws. A site that mounts search elsewhere sets its own;
+    # blank it to disable the affordance without touching #search.
+    attr_accessor :search_path
+    # The keyboard shortcut STRINGS that open the search palette, e.g.
+    # %w[/ mod+k s]. Defaults to DEFAULT_SEARCH_SHORTCUTS (["/", "mod+k"] — the
+    # keys shipped before this was configurable, so existing sites are unchanged).
+    # "mod" is the platform modifier (⌘ on mac, Ctrl elsewhere), so one entry
+    # works on every OS. Read the parsed form via #search_shortcuts (which maps to
+    # DocsKit::Shortcut and drops anything unparseable), never @search_shortcuts.
+    attr_writer :search_shortcuts
+    # The API base URL prefixed onto a DocsUI::RequestExample path so copy-pasted
+    # snippets point at a real host. Defaults to a neutral example host; a site
+    # sets its own (e.g. "https://api.acme.com").
+    attr_accessor :api_base_url
+    # An example Authorization header line merged into every generated request
+    # snippet (e.g. "Authorization: Bearer sk_live_..."). Defaults to nil → no
+    # auth line, so a site with no auth example renders clean snippets.
+    attr_accessor :api_auth_header
+    # Site overrides/extensions for the DocsUI::RequestExample client tabs — an
+    # ordered { token => DocsKit::ApiClient } Hash merged OVER the four shipped
+    # defaults (curl, javascript, ruby, python). Reusing a default token replaces
+    # that client (SDK-flavored snippet); a new token appends a tab (e.g. a `cli`).
+    # Read the effective map via #api_clients (which merges), never @api_clients.
+    attr_writer :api_clients
+    # 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
+    # normalizes them into TopbarLink value objects. Defaults to [] → the topbar
+    # is byte-identical to before, so a site that sets nothing is unchanged.
+    # `icon` is a shipped brand mark (:github, :discord, …) or a lucide icon
+    # name. Read the normalized list via #topbar_links, never @topbar_links.
+    attr_writer :topbar_links
+    # The OpenAPI spec the `operation` page helper / DocsUI::OpenApiOperation read
+    # from: a String/Pathname path (`.json` parsed as JSON, else YAML) or an
+    # already-parsed Hash. Defaults to nil → the bridge is off and a site that
+    # doesn't set it is byte-identical to before. Read the loaded model via
+    # #openapi_document (which memoizes + reloads on file change), never @openapi.
+    attr_accessor :openapi
+    # The sentinel "no explicit nav" lambda. #nav_groups compares against this
+    # identity to decide whether to derive the sidebar from #nav_registries.
+    DEFAULT_NAV = -> { {} }
+    # The search-palette shortcuts before this was configurable — "/" and the
+    # platform command chord — so a site that never sets #search_shortcuts keeps
+    # exactly the previous behavior.
+    DEFAULT_SEARCH_SHORTCUTS = ["/", "mod+k"].freeze
+    # The built-in daisyUI theme names that are dark. #dark_themes defaults to
+    # this; #dark_themes_shipped intersects it with the site's #themes so only
+    # shipped themes ever generate dark code CSS. A site with custom dark themes
+    # overrides #dark_themes (docs-kit can't see the compiled daisyUI CSS to
+    # detect darkness at render time, so an honest static list + override wins).
+    DEFAULT_DARK_THEMES = %w[
+      dark synthwave halloween forest black luxury dracula
+      business night coffee dim sunset abyss
+    ].freeze
+    # Built-in friendly aliases (kept small — Rouge resolves most names itself).
+    DEFAULT_LEXER_ALIASES = { curl: "console", console: "console" }.freeze
+    # Built-in tab labels for the common languages that don't just capitalize.
+    DEFAULT_LANGUAGE_LABELS = {
+      javascript: "JavaScript", typescript: "TypeScript", php: "PHP",
+      curl: "cURL", json: "JSON", yaml: "YAML", html: "HTML", css: "CSS",
+      erb: "ERB", jsx: "JSX", tsx: "TSX", sql: "SQL", graphql: "GraphQL"
+    }.freeze
+    def initialize
+      @brand = "Docs"
+      @tagline = nil
+      @brand_href = "/"
+      @title_suffix = nil
+      @themes = %w[dark light]
+      @default_theme = nil
+      # The default nav lambda. Until a site assigns #nav (which sets
+      # @nav_explicit), #nav_groups treats nav as "unset" and derives the sidebar
+      # from #nav_registries instead; an explicit c.nav (any lambda) then wins.
+      @nav = DEFAULT_NAV
+      @nav_explicit = false
+      @nav_registries = {}
+      @version_badge = nil
+      @stylesheets = %w[application]
+      @code_theme = "Rouge::Themes::Monokai"
+      @code_theme_dark = nil
+      @dark_themes = DEFAULT_DARK_THEMES
+      @default_group_icon = "file-text"
+      @icon_library = "lucide"
+      @nav_storage_key = nil
+      @on_page_default = :panel
+      @code_lexer_aliases = {}
+      @code_lexer_fallback = "plaintext"
+      @code_language_labels = {}
+      @page_markdown_action = true
+      @mcp = true
+      @search = true
+      @search_path = "/docs/search"
+      @search_shortcuts = DEFAULT_SEARCH_SHORTCUTS
+      @api_base_url = "https://api.example.com"
+      @api_auth_header = nil
+      @api_clients = {}
+      @topbar_links = []
+      @openapi = nil
+    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 [].
+    def topbar_links
+      Array(@topbar_links).map { |link| DocsKit::TopbarLink.from(link) }
+    end
+    # The loaded DocsKit::OpenApi::Document for #openapi. Memoized; when #openapi
+    # is a file path, the memo is invalidated on an mtime change so editing the
+    # spec in development is picked up without a server restart. Raises a
+    # DocsKit::Error naming the knob when read while #openapi is unset — a missing
+    # spec has nothing useful to degrade to.
+    def openapi_document
+      raise DocsKit::Error, "no OpenAPI spec configured — set c.openapi to a path or Hash" if @openapi.nil?
+      mtime = openapi_source_mtime
+      return @openapi_document if defined?(@openapi_document) && @openapi_document_mtime == mtime
+      @openapi_document_mtime = mtime
+      @openapi_document = DocsKit::OpenApi.load(@openapi)
+    end
+    # The effective client map for DocsUI::RequestExample: the four shipped
+    # defaults with site overrides/extensions merged over them. Hash#merge keeps
+    # a reused token in its original position and appends new tokens in
+    # declaration order, so tab order is stable and predictable.
+    def api_clients
+      DocsKit::ApiClient::DEFAULTS.merge(@api_clients || {})
+    end
+    # The effective alias map (built-ins + site overrides), symbol-keyed.
+    def lexer_aliases
+      DEFAULT_LEXER_ALIASES.merge((@code_lexer_aliases || {}).transform_keys(&:to_sym))
+    end
+    # The effective label map (built-ins + site overrides), symbol-keyed.
+    def language_labels
+      DEFAULT_LANGUAGE_LABELS.merge((@code_language_labels || {}).transform_keys(&:to_sym))
+    end
+    # The auto-TOC placements, all driven by the same docs-nav Stimulus
+    # controller (it reads the page's headings from the DOM):
+    #   :panel   — a sticky card in the top-right of the content column
+    #   :toggle  — a sticky floating button (top-right) opening a dropdown
+    #   :sidebar — nested under the active nav item in the left sidebar
+    ON_PAGE_MODES = %i[panel toggle sidebar].freeze
+    # The resolved default placement (a mode symbol or false). A bare `true`
+    # default means :panel (the canonical default), never a self-reference.
+    def on_page_default
+      raw = @on_page_default
+      raw = :panel if raw == true
+      coerce_on_page_mode(raw)
+    end
+    # Coerce a per-page on_page: value to a valid mode symbol or false. `true`
+    # means "use the configured default".
+    def normalize_on_page(value)
+      return on_page_default if value == true
+      coerce_on_page_mode(value)
+    end
+    private
+    # True when the optional `mcp` gem can be loaded. Memoized across both
+    # outcomes so a site without the gem doesn't pay a failed require per request.
+    # We attempt the require lazily (rather than only checking defined?(MCP)) so a
+    # bundled-but-not-yet-required gem still counts as present — the same
+    # degrade-gracefully-on-a-missing-optional-gem posture as DocsUI::Icon's
+    # rails_icons guard.
+    def mcp_gem_present?
+      return @mcp_gem_present if defined?(@mcp_gem_present)
+      @mcp_gem_present =
+        begin
+          require "mcp"
+          defined?(::MCP::Server) ? true : false
+        rescue LoadError
+          false
+        end
+    end
+    # The mtime of the #openapi source when it's a readable file path, else nil
+    # (a Hash spec, or a path that isn't a file). Drives #openapi_document's
+    # reload-on-change memoization; a Hash spec loads once and never invalidates.
+    def openapi_source_mtime
+      return if @openapi.is_a?(Hash)
+      path = Pathname.new(@openapi)
+      path.file? ? path.mtime : nil
+    rescue StandardError
+      nil
+    end
+    # { heading => registry.nav_items }, dropping headings with no authored
+    # pages so the sidebar never shows an empty group.
+    def nav_groups_from_registries
+      @nav_registries.each_with_object({}) do |(heading, registry), acc|
+        items = registry.nav_items
+        acc[heading] = items unless items.empty?
+      end
+    end
+    def coerce_on_page_mode(value)
+      case value
+      when false, nil then false
+      when *ON_PAGE_MODES then value.to_sym
+      else
+        raise ArgumentError,
+              "on_page must be one of #{ON_PAGE_MODES.inspect}, true, or false (got #{value.inspect})"
+      end
+    end
+    public
+    def nav_storage_key
+      @nav_storage_key || @brand.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+    def title_suffix
+      @title_suffix || @brand
+    end
+    # Whether the built-in MCP endpoint is active: the #mcp toggle is on AND the
+    # optional `mcp` gem is loadable — the same "toggle AND capability" shape as
+    # #search_enabled?. Read by DocsKit::LlmsText (to advertise /mcp in llms.txt)
+    # and DocsKit::McpController (to 404 when off), so a site without the gem, or
+    # one that set c.mcp = false, is byte-identical to before this feature.
+    def mcp_enabled?
+      !!@mcp && mcp_gem_present?
+    end
+    # Whether the Shell renders the search affordance: search is on AND a path is
+    # set to submit to. A site with @search_path blanked (or nil) gets no form
+    # even if @search is true — there'd be nothing to submit to.
+    def search_enabled?
+      !!@search && !@search_path.to_s.empty?
+    end
+    # The parsed search-palette shortcuts (DocsKit::Shortcut list), with anything
+    # unparseable dropped. The topbar renders one <kbd> per entry and docs-nav
+    # binds each; an empty list means no keyboard shortcut (the form still works).
+    def search_shortcuts
+      DocsKit::Shortcut.parse_list(@search_shortcuts)
+    end
+    def default_theme
+      @default_theme || Array(@themes).first
+    end
+    # The resolved nav Hash for this request. Always returns a Hash.
+    #
+    # An explicit #nav lambda wins. Otherwise the sidebar derives from
+    # #nav_registries: each heading maps to its registry's .nav_items, and a
+    # heading whose pages are all unauthored (empty nav_items) is dropped so no
+    # empty group renders.
+    def nav_groups
+      return nav_groups_from_registries unless @nav_explicit
+      result = @nav.respond_to?(:call) ? @nav.call : @nav
+      result || {}
+    end
+    # The resolved version badge string, or nil.
+    # The rendered version badge. A callable is invoked; a plain String (or any
+    # non-nil value) is coerced to its string form — so `c.version_badge = "v1.2"`
+    # renders, not only a lambda.
+    def version_badge_text
+      return if @version_badge.nil?
+      return @version_badge.call if @version_badge.respond_to?(:call)
+      @version_badge.to_s
+    end
+    # The default Rouge theme both #code_theme_class and #code_theme_dark_class
+    # fall back to when a configured theme name can't be resolved — so a typo'd
+    # theme name degrades gracefully instead of raising on every code block.
+    DEFAULT_CODE_THEME = "Rouge::Themes::Monokai"
+    # The Rouge theme class resolved from #code_theme (String or class). A String
+    # name that doesn't resolve degrades to the default theme rather than raising
+    # NameError on every DocsUI::Code render.
+    def code_theme_class
+      return @code_theme if @code_theme.is_a?(Class)
+      resolve_theme(@code_theme) || Object.const_get(DEFAULT_CODE_THEME)
+    end
+    # The dark Rouge theme class resolved from #code_theme_dark (String or
+    # class), or nil when unset — mirrors #code_theme_class. DocsUI::Code emits
+    # dark code CSS only when this is non-nil, so an unresolvable name degrades to
+    # nil (no dark restyle) rather than raising.
+    def code_theme_dark_class
+      return if @code_theme_dark.nil?
+      return @code_theme_dark if @code_theme_dark.is_a?(Class)
+      resolve_theme(@code_theme_dark)
+    end
+    # The dark themes the site actually ships: #dark_themes intersected with
+    # #themes, in #themes declaration order. DocsUI::Code scopes the dark theme's
+    # CSS under [data-theme=X] for each of these, so a dark theme that isn't in
+    # the Tailwind build never emits dead CSS.
+    def dark_themes_shipped
+      Array(@themes) & Array(@dark_themes)
+    end
+    private
+    # Resolve a Rouge theme constant from its String name, returning nil (not
+    # raising) when the name doesn't resolve — a typo'd or unloaded theme must
+    # not crash every code block on the page.
+    def resolve_theme(name)
+      Object.const_get(name.to_s)
+    rescue NameError
+      nil
+    end
+  end
+end

data/lib/docs_kit/controller.rb ADDED Viewed

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+module DocsKit
+  # Controller glue for a docs site. Include in ApplicationController to get the
+  # one shared render helper.
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include DocsKit::Controller
+  #     def show = render_page(Views::Landings::Show.new)
+  #   end
+  module Controller
+    # Render a Phlex page that is itself a full HTML document (it composes
+    # Docs::Shell, which emits <html>/<head>/<body>). `layout: false` prevents the
+    # Rails ERB application layout from double-nesting <html>. phlex-rails still
+    # renders through a real view context, so CSRF, dom_id, url helpers, and the
+    # phlex-reactive token signer all work inside components.
+    #
+    # A `.md`/`.text` request instead returns the page's Markdown twin, derived
+    # from the SAME render (DocsKit::MarkdownExport walks the rendered HTML). So
+    # `GET /docs/x.md` is faithful GFM of exactly what `/docs/x` shows — the
+    # author writes nothing extra, and the two never drift.
+    def render_page(view)
+      return render_markdown(view) if markdown_request?
+      render view, layout: false
+    end
+    private
+    # True for a `.md` or `.text` request. `.text` is accepted as an alias so a
+    # host whose routes only allow the built-in `:text` format still gets the
+    # twin.
+    def markdown_request?
+      request.format.md? || request.format.text?
+    end
+    # The Markdown twin as text/markdown. Rendered through the controller's view
+    # context (so url helpers/CSRF resolve) and with the request base URL so
+    # relative links in the export are absolutized to portable URLs.
+    def render_markdown(view)
+      markdown = DocsKit::MarkdownExport.new(
+        view, view_context:, base_url: request.base_url
+      ).to_md
+      render plain: markdown, content_type: "text/markdown"
+    end
+  end
+end

data/lib/docs_kit/engine.rb ADDED Viewed

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+require "rails/engine"
+module DocsKit
+  # An asset/glue engine (no isolate_namespace, no routes/models). It makes the
+  # gem's Phlex components autoloadable in the host app and exposes the controller
+  # helper, so a docs site only adds the gem + its DocsKit.configure block.
+  class Engine < ::Rails::Engine
+    # The gem's OWN zeitwerk loader (in lib/docs_kit.rb) is the single owner of
+    # the Docs::* components under app/components/docs. Rails would otherwise also
+    # add an engine's app/* dirs to the host autoload paths and double-manage
+    # those constants, so opt this engine's app/ out of Rails autoloading.
+    config.autoload_paths = []
+    config.eager_load_paths = []
+    config.paths["app"].skip_eager_load!
+    JAVASCRIPT_PATH = root.join("app/javascript")
+    initializer "docs_kit.controller_helper" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include DocsKit::Controller
+      end
+    end
+    # Register the :md format (text/markdown) so a `.md` request routes and
+    # `request.format.md?` is true — the trigger for the page's Markdown twin
+    # (DocsKit::Controller#render_page). Guarded so re-registration (a host that
+    # already declared :md) is a no-op rather than a duplicate-type error.
+    initializer "docs_kit.mime_types" do
+      Mime::Type.register("text/markdown", :md) unless Mime::Type.lookup_by_extension(:md)
+    end
+    # Serve the bundled Stimulus controller (docs_nav) as an asset.
+    initializer "docs_kit.assets" do |app|
+      app.config.assets.paths << JAVASCRIPT_PATH.to_s if app.config.respond_to?(:assets)
+    end
+    # Auto-pin the controller for importmap-rails consumers, so a host app gets
+    # `docs_kit/controllers/docs_nav_controller` with no manual pin.
+    initializer "docs_kit.importmap", before: "importmap" do |app|
+      next unless app.config.respond_to?(:importmap)
+      importmap = app.config.importmap
+      importmap.paths << root.join("config/importmap.rb") if importmap.respond_to?(:paths)
+      importmap.cache_sweepers << JAVASCRIPT_PATH if importmap.respond_to?(:cache_sweepers)
+    end
+  end
+end

data/lib/docs_kit/llms_text.rb ADDED Viewed

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+module DocsKit
+  # Builds the two AI-readable artifacts a docs-kit site serves, straight from
+  # the registry — zero authoring:
+  #
+  #   /llms.txt      — the llmstxt.org index: H1 brand, `> tagline` blockquote,
+  #                    one `## {group}` section per nav group, and a
+  #                    `- [title](abs .md url)` line per authored page.
+  #   /llms-full.txt — every page's Markdown twin concatenated, `# {title}` +
+  #                    body, separated by `---`.
+  #
+  # It's a pure text builder: given a DocsKit::Configuration and (for the full
+  # form) already-rendered `[title, markdown]` pairs, it produces strings with no
+  # Rails. The controller owns the Rails view context — it renders each page to
+  # Markdown (DocsKit::MarkdownExport) and hands the pairs to .full — so all the
+  # shaping is unit-testable without booting Rails.
+  #
+  # The enumeration source is DocsKit::Registry v2: each registry in
+  # `config.nav_registries` responds to #nav_items ({ group => [NavItem] },
+  # authored pages only) for the index and #all (entries with #view_class) for
+  # the authored page list. An unwritten page (no resolvable view_class) is
+  # excluded from both, so neither artifact ever links or concatenates a page
+  # that doesn't exist yet.
+  module LlmsText
+    module_function
+    # The llms.txt index string. base_url absolutizes each page's `.md` href so
+    # agent tooling fetches a portable URL; omit it for relative links.
+    #
+    # Blocks (H1, the tagline blockquote, and one per section) are separated by a
+    # blank line; within a section the `## heading` and its `- [..]` bullets are a
+    # single tight list (no blank lines between bullets), per the llmstxt.org
+    # convention.
+    def index(config, base_url: nil)
+      blocks = ["# #{config.brand}"]
+      tagline = config.tagline
+      blocks << "> #{tagline}" if tagline && !tagline.to_s.empty?
+      blocks.concat(section_blocks(config, base_url))
+      # Advertise the built-in MCP endpoint last, so an agent that reads llms.txt
+      # discovers it can also connect over the protocol (native tools vs fetching
+      # text). Only when the endpoint is actually live (gem present + c.mcp on).
+      blocks << mcp_block(base_url) if config.mcp_enabled?
+      blocks.join("\n\n")
+    end
+    # One `## {group}` block per nav group, each a tight bullet list of its
+    # authored pages' `.md` links, in registry order.
+    def section_blocks(config, base_url)
+      groups(config).map do |group, links|
+        ["## #{group}", *links.map { |link| link_line(link, base_url) }].join("\n")
+      end
+    end
+    # The authored pages across every registry, in config/registry order — each
+    # responds to #title / #href / #view_class. The controller renders these to
+    # Markdown for .full.
+    def pages(config)
+      config.nav_registries.values.flat_map { |registry| registry.all.select(&:view_class) }
+    end
+    # The llms-full.txt body: each [title, markdown] pair as `# {title}` + body,
+    # separated by a `---` rule. Empty pairs → "".
+    def full(_config, title_markdown_pairs)
+      title_markdown_pairs.map { |title, markdown| "# #{title}\n\n#{markdown}" }.join("\n\n---\n\n")
+    end
+    # { group => [links] } across every registry's #nav_items, in config order.
+    # A registry with no authored pages contributes nothing, so no empty section
+    # is ever emitted.
+    def groups(config)
+      config.nav_registries.values.each_with_object({}) do |registry, acc|
+        registry.nav_items.each { |group, links| (acc[group] ||= []).concat(links) }
+      end
+    end
+    # The `## MCP` section pointing an agent at the read-only MCP endpoint. The
+    # `/mcp` URL is absolutized against base_url when available (agents connect to
+    # a portable URL); relative otherwise.
+    def mcp_block(base_url)
+      url = base_url ? "#{base_url.chomp('/')}/mcp" : "/mcp"
+      "## MCP\n" \
+        "This documentation is also available over the Model Context Protocol " \
+        "(search, page retrieval) at #{url} — add it to an MCP client " \
+        "(Claude Code, Claude.ai, Cursor) to query these docs as tools."
+    end
+    # `- [label](absolute .md url)`. The `.md` suffix targets the page's Markdown
+    # twin (DocsKit::Controller#render_page).
+    def link_line(link, base_url)
+      "- [#{link.label}](#{md_url(link.href, base_url)})"
+    end
+    # href + ".md", absolutized against base_url when given. base_url has no
+    # trailing slash concerns here (hrefs are root-relative like "/docs/x").
+    def md_url(href, base_url)
+      path = "#{href}.md"
+      return path unless base_url
+      "#{base_url.chomp('/')}#{path}"
+    end
+  end
+end