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/app/components/docs_ui/table.rb ADDED Viewed

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+module DocsUI
+  # A generic reference table — headers + rows — in the kit's daisyUI look (a
+  # `table table-sm table-zebra` inside a `rounded-box` border, `not-prose` so the
+  # surrounding Prose typography doesn't restyle it). This is the piece every docs
+  # site was hand-rolling; compose it, don't write raw `table`/`tr`/`td` markup.
+  #
+  #   render DocsUI::Table.new(
+  #     ["Option", "Type", "Default", "Description"],
+  #     [
+  #       ["brand", "String", '"Docs"', "Topbar + sidebar heading."],
+  #       ["themes", [:code, "%w[dark light]"], "—", "ThemeSwitcher options."],
+  #     ]
+  #   )
+  #
+  # Cell values (the same convention the dogfood PropTable proved):
+  #
+  #   * String        → plain text (Phlex-escaped; HTML in it is inert, never live)
+  #   * [:code, "x"]  → inline <code> (for a type, a default literal, an identifier)
+  #   * [:md, "…"]    → inline GFM through DocsUI::Markdown (bold/links/inline code),
+  #                     opt-in so a plain String that merely *looks* like markdown
+  #                     is never surprise-parsed.
+  #
+  # PropTable is a thin preset over this (name/type/default/description, first
+  # column auto-code-styled).
+  class Table < Phlex::HTML
+    WRAPPER = "not-prose my-4 overflow-x-auto rounded-box border border-base-300"
+    TABLE = "table table-sm table-zebra"
+    def initialize(headers, rows)
+      @headers = headers
+      @rows = rows
+    end
+    def view_template
+      div(class: WRAPPER) do
+        table(class: TABLE) do
+          thead do
+            tr { @headers.each { |header| th(class: "whitespace-nowrap") { plain header.to_s } } }
+          end
+          tbody do
+            @rows.each { |cells| tr { cells.each { |cell| td { render_cell(cell) } } } }
+          end
+        end
+      end
+    end
+    private
+    # Dispatch a cell by its shape. A [type, value] pair selects an inline
+    # renderer; anything else is plain, Phlex-escaped text.
+    def render_cell(cell)
+      case cell
+      in [:code, value] then code(class: "text-sm") { plain value.to_s }
+      in [:md, value] then render DocsUI::Markdown.inline(value.to_s)
+      in [Symbol => _tag, *]
+        raise ArgumentError,
+              "DocsUI::Table: unknown or malformed typed cell #{cell.inspect}; use [:code, value] or [:md, value]"
+      else plain cell.to_s
+      end
+    end
+  end
+end

data/app/components/docs_ui/theme_switcher.rb ADDED Viewed

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+module DocsUI
+  # daisyUI theme switcher — a dropdown of radio inputs with the `theme-controller`
+  # class. daisyUI swaps the page theme (data-theme on :root) via a CSS :has()
+  # selector; the docs-nav Stimulus controller additionally PERSISTS the choice to
+  # localStorage (change->docs-nav#selectTheme) and re-applies it on connect, and
+  # the anti-flash <head> script (DocsUI::Shell) restores it before first paint —
+  # so the theme survives navigation without a flicker.
+  #
+  # The offered themes come from DocsKit.configuration.themes and MUST match the
+  # themes enabled in the site's Tailwind @plugin "daisyui" { themes: ... } block.
+  class ThemeSwitcher < Phlex::HTML
+    def view_template
+      div(class: "dropdown dropdown-end") do
+        div(tabindex: "0", role: "button", class: "btn btn-sm btn-ghost gap-1") do
+          render DocsUI::Icon.new("palette", class: "size-4")
+          plain "Theme"
+        end
+        ul(tabindex: "0",
+           class: "dropdown-content bg-base-300 rounded-box z-10 w-44 p-2 shadow-2xl max-h-96 overflow-y-auto") do
+          themes.each { |theme| theme_option(theme) }
+        end
+      end
+    end
+    private
+    def themes
+      DocsKit.configuration.themes
+    end
+    def theme_option(theme)
+      li do
+        input(
+          type: "radio",
+          name: "theme-dropdown",
+          value: theme,
+          class: "theme-controller btn btn-sm btn-block btn-ghost justify-start",
+          aria_label: theme.capitalize,
+          data: { testid: "theme-#{theme}", action: "change->docs-nav#selectTheme" }
+        )
+      end
+    end
+  end
+end

data/app/components/docs_ui/topbar_links.rb ADDED Viewed

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+module DocsUI
+  # The config-driven repo/social links in the topbar, next to the theme switcher
+  # (DocsKit.configuration.topbar_links). Each link renders as an icon-only ghost
+  # button — a DocsUI::BrandMark (a shipped brand glyph like GitHub/Discord, or a
+  # lucide fallback) whose accessible name is the link's #label. External links
+  # open in a new tab with rel=noopener; a site-relative link opens in place.
+  #
+  # Renders nothing when the site configures no links, so a site that sets
+  # c.topbar_links = [] (the default) has a byte-identical topbar.
+  class TopbarLinks < Phlex::HTML
+    def view_template
+      links = DocsKit.configuration.topbar_links
+      return if links.empty?
+      links.each { |link| topbar_link(link) }
+    end
+    private
+    def topbar_link(link)
+      # An icon-only button when the link names an icon (square), else a text
+      # button showing the label — so an icon-less link is never a blank button.
+      icon = link.icon
+      a(
+        href: link.href,
+        class: "btn btn-sm btn-ghost #{'btn-square' if icon}",
+        aria_label: link.label,
+        title: link.label,
+        target: (link.external? ? "_blank" : nil),
+        rel: (link.external? ? "noopener noreferrer" : nil)
+      ) do
+        if icon
+          render DocsUI::BrandMark.new(icon, label: link.label, class: "size-5")
+        else
+          plain link.label
+        end
+      end
+    end
+  end
+end

data/app/controllers/docs_kit/llms_controller.rb ADDED Viewed

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+module DocsKit
+  # Serves the two AI-readable artifacts (llmstxt.org) from the registry, with
+  # zero authoring — the host app wires the routes (the engine is glue-only, no
+  # routes of its own), so a site keeps full control over path, auth, and
+  # omission:
+  #
+  #   # config/routes.rb
+  #   get "/llms.txt"      => "docs_kit/llms#index"
+  #   get "/llms-full.txt" => "docs_kit/llms#full"
+  #
+  # #index → the llms.txt index (brand, tagline, nav-grouped links to each page's
+  # `.md` twin). #full → llms-full.txt (every page's Markdown concatenated). Both
+  # are text/plain and HTTP-cached: the response revalidates on the registry's
+  # own content plus DocsKit::VERSION, so a page/gem change busts the cache while
+  # an unchanged registry serves a 304.
+  #
+  # All the text shaping lives in DocsKit::LlmsText (pure, Rails-free). This
+  # controller only threads the Rails view context: #full renders each page to
+  # Markdown via DocsKit::MarkdownExport (which needs url helpers/CSRF), then
+  # hands the [title, markdown] pairs to LlmsText.full.
+  class LlmsController < ActionController::Base
+    # #full renders each page's full HTML through this controller's view context
+    # (DocsKit::MarkdownExport), and DocsUI::Shell's <head> calls csrf_meta_tags —
+    # which needs protect_against_forgery? registered as a view helper. A gem's
+    # bare ActionController::Base subclass doesn't inherit the host app's
+    # default_protect_from_forgery, so declare it here. :null_session fits these
+    # GET-only, sessionless, public text endpoints (no token to verify).
+    protect_from_forgery with: :null_session
+    def index
+      body = DocsKit::LlmsText.index(docs_config, base_url: request.base_url)
+      render_text(body) if stale_llms?(body)
+    end
+    def full
+      pairs = DocsKit::LlmsText.pages(docs_config).map do |page|
+        [page.title, render_page_markdown(page)]
+      end
+      body = DocsKit::LlmsText.full(docs_config, pairs)
+      render_text(body) if stale_llms?(body)
+    end
+    private
+    # NOT named #config — ActionController::Base#config is the Rails config
+    # object, and RequestForgeryProtection delegates allow_forgery_protection/
+    # csrf_token_storage_strategy to it (`delegate ..., to: :config`). Shadowing
+    # #config with DocsKit.configuration would route those to the wrong object and
+    # blow up csrf_meta_tags when #full renders a page's <head>.
+    def docs_config = DocsKit.configuration
+    # text/plain (llms.txt is plain text, not markdown — agent tooling fetches it
+    # as-is). UTF-8 because page titles/taglines may carry non-ASCII.
+    def render_text(body)
+      render plain: body, content_type: "text/plain; charset=utf-8"
+    end
+    # Revalidate on the rendered body itself (so any registry/config/page change
+    # busts it) plus the gem version as the etag salt. In development, always
+    # re-render; production sites deploy immutably so the version etag is stable.
+    def stale_llms?(body)
+      stale?(etag: [DocsKit::VERSION, body], public: true)
+    end
+    # A page's Markdown twin, rendered through this controller's view context so
+    # url helpers/CSRF resolve and relative links absolutize to portable URLs —
+    # the same path DocsKit::Controller#render_page takes for a `.md` request.
+    def render_page_markdown(page)
+      DocsKit::MarkdownExport.new(
+        page.view_class.new, view_context:, base_url: request.base_url
+      ).to_md
+    end
+  end
+end

data/app/controllers/docs_kit/mcp_controller.rb ADDED Viewed

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+module DocsKit
+  # The built-in read-only MCP endpoint — one gem controller, host-drawn route
+  # (same shape as DocsKit::LlmsController/SearchController; the engine adds no
+  # routes):
+  #
+  #   # config/routes.rb
+  #   post  "/mcp" => "docs_kit/mcp#create"
+  #   match "/mcp" => "docs_kit/mcp#method_not_allowed", via: %i[get delete]
+  #
+  # A user adds `https://docs.example.com/mcp` to Claude Code / Claude.ai / Cursor
+  # once and the docs become first-class agent tools (list_pages / get_page /
+  # search_docs) over the SAME registry the site renders from. See
+  # DocsKit::McpServer / DocsKit::McpTools.
+  #
+  # Stateless JSON-RPC: each POST is independent (no SSE session), so it works
+  # behind the existing Kamal/Cloudflare deploy unchanged. #create delegates the
+  # whole protocol to DocsKit::McpServer#handle_json — the SDK parses the request,
+  # dispatches the tool, and serializes the response (including JSON-RPC errors),
+  # so the controller never hand-rolls the protocol.
+  #
+  # OFF unless BOTH the optional `mcp` gem is present AND the site left c.mcp on
+  # (DocsKit.configuration#mcp_enabled?). A site without the gem, or with
+  # c.mcp = false, gets a 404 here and is byte-identical to before this feature.
+  class McpController < ActionController::Base
+    # A JSON-RPC POST carries no CSRF token to verify (there's no form, no
+    # session — an agent posts a raw JSON body). Unlike the GET-only text
+    # endpoints (which use :null_session so csrf_meta_tags resolves in a rendered
+    # <head>), this action renders JSON only and never a Shell, so drop forgery
+    # protection outright.
+    skip_forgery_protection
+    def create
+      return head(:not_found) unless docs_config.mcp_enabled?
+      server = DocsKit::McpServer.build(docs_config, base_url: request.base_url, view_context:)
+      return head(:not_found) unless server
+      # #handle_json returns an already-serialized JSON string, so render it as the
+      # raw body with the JSON content type — `render json:` would re-encode the
+      # string (wrapping it in quotes), corrupting the JSON-RPC envelope.
+      render body: server.handle_json(request.body.read), content_type: "application/json"
+    end
+    # Read-only + stateless: the endpoint speaks JSON-RPC over POST only. There is
+    # no standalone SSE stream (GET) and no session to terminate (DELETE), so both
+    # are 405 rather than the SDK's session machinery.
+    def method_not_allowed
+      head :method_not_allowed
+    end
+    private
+    # NOT named #config — ActionController::Base#config is the Rails config object
+    # and RequestForgeryProtection delegates to it; shadowing it breaks forgery
+    # handling (see LlmsController). The DocsKit config reader is #docs_config.
+    def docs_config = DocsKit.configuration
+  end
+end

data/app/controllers/docs_kit/search_controller.rb ADDED Viewed

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+module DocsKit
+  # Serves the docs search — one gem controller, host-drawn route (same shape as
+  # DocsKit::LlmsController; the engine is glue-only and adds no routes):
+  #
+  #   # config/routes.rb
+  #   get "/docs/search" => "docs_kit/search#index"
+  #
+  # #index answers BOTH formats off the same index:
+  #
+  #   * html — the JS-off path: renders DocsUI::SearchResults inside DocsUI::Shell,
+  #     a full working results page. The topbar form (GET ?q=) lands here.
+  #   * json — the enhancement path: the docs-nav palette fetches `search.json?q=`
+  #     debounced and renders the hits client-side. The form still submits to the
+  #     html path if JS dies mid-typing.
+  #
+  # The index is built lazily per request from DocsKit::SearchIndex, whose entries
+  # come from each registry page's Markdown twin (DocsKit::MarkdownExport) split on
+  # its `## ` headings — the SAME twins llms-full.txt serves, so search can never
+  # drift from the pages. Sites are tens of pages; there's no external index, no
+  # build step, no second registry.
+  class SearchController < ActionController::Base
+    # Like LlmsController: a bare ActionController::Base subclass doesn't inherit
+    # the host's default_protect_from_forgery, and #index renders DocsUI::Shell,
+    # whose <head> calls csrf_meta_tags (which needs protect_against_forgery?
+    # registered as a view helper). :null_session fits this GET-only, sessionless,
+    # public endpoint.
+    protect_from_forgery with: :null_session
+    def index
+      hits = search_index.search(query)
+      respond_to do |format|
+        format.html { render_results_page(hits) }
+        format.json { render json: { "query" => query, "results" => hits.map(&:as_json) } }
+      end
+    end
+    private
+    # NOT named #config — ActionController::Base#config is the Rails config object
+    # and RequestForgeryProtection delegates to it; shadowing it breaks
+    # csrf_meta_tags when the Shell renders (see LlmsController).
+    def docs_config = DocsKit.configuration
+    def query = params[:q].to_s
+    # The index built from every authored registry page's Markdown twin. Each page
+    # is rendered through THIS controller's view context (url helpers/CSRF resolve)
+    # and absolutized against the request base URL, exactly as LlmsController#full
+    # renders each twin.
+    def search_index
+      triples = DocsKit::LlmsText.pages(docs_config).map do |page|
+        markdown = DocsKit::MarkdownExport.new(
+          page.view_class.new, view_context:, base_url: request.base_url
+        ).to_md
+        [page.title, page.href, markdown]
+      end
+      DocsKit::SearchIndex.new(triples)
+    end
+    # The full chrome results page. DocsUI::Shell IS the whole document, so render
+    # with layout: false (the same contract as DocsKit::Controller#render_page).
+    def render_results_page(hits)
+      page = DocsUI::Shell.new(title: "Search") do
+        render DocsUI::SearchResults.new(query:, hits:)
+      end
+      render page, layout: false
+    end
+  end
+end