docs-kit
GitHub
Theme
Getting started

Overview

The shared Phlex chrome for a Rails docs site — you write page bodies, docs-kit renders the rest.

What is docs-kit#

A gem, not a template.

docs-kit is a Ruby gem that gives you the shared chrome for a Rails documentation site: the topbar, the responsive sidebar, the theme switcher, the content column, an automatic "On this page" TOC, and syntax-highlighted code blocks.

It's built on phlex-rails and daisyUI. You write page bodies as Phlex components — docs-kit renders everything around them.

The mental model#

Configure the chrome; don't re-author it.

The chrome — Shell, Sidebar, Page — is byte-identical across every site that uses docs-kit. The only thing that differs is DocsKit.configure. Two sites look and behave consistently for free, because they share the same components. You change the brand, the themes, and the nav — never the layout code.

config/initializers/docs_kit.rb
DocsKit.configure do |c|
  c.brand          = "My Project"          # only this differs per site
  c.themes         = %w[dark light]        # the chrome itself is identical
  c.nav_registries = { "Docs" => Doc }     # sidebar derives from the registry
end
This very site is built with docs-kit — the topbar, sidebar, and TOC you're looking at are the exact chrome your site will get.

What you get#

The whole surface, in the box — each row links to its page.

The chrome

  • Shared shell + responsive sidebar + theme switcher — the same topbar, nav, and layout on every screen size, remembered in localStorage. See Components.
  • A theme switcher whose list is your c.themes — it must match the daisyUI @plugin block in your Tailwind entry. See Styling & CSS.
  • Syntax highlighting for ~200 languages via Rouge, with a light + dark theme pair emitted as inline CSS — no allowlist, no flash. See Code languages.

Authoring

  • Markdown islands — drop md <<~'MD' … MD anywhere in a page and get GFM (tables, lists, inline code, links) styled with the reading rhythm. See Markdown authoring.
  • The component kit — Section, Code, Example, Callout, Table/PropTable, plus the API-docs kit (Endpoint, RequestExample, JsonResponse) that turns one request declaration into every client tab. See Components and the API reference.
  • A one-command page generator — rails g docs_kit:page "Title" writes the Phlex class AND its one-line Registry v2 entry, both derived from the title. See Authoring pages.

For machines

  • An automatic .md twin — every page answers at /docs/x.md with its Markdown source, and the masthead "Markdown" action becomes copy-to-clipboard.
  • /llms.txt + /llms-full.txt — an llmstxt.org index and a full concatenation, served from the registry with zero authoring.
  • Server-rendered search + a ⌘K palette — a working GET /docs/search form the docs-nav controller enhances into a fuzzy palette. See Search.
  • An optional read-only MCP server — POST /mcp exposing list_pages / get_page / search_docs over the registry when the mcp gem is present. See AI & agents.
  • AGENTS.md scaffolding — the install generator writes an AGENTS.md authoring contract plus a Claude Code write-docs-page skill, so agents author pages the right way.

Toolchain

  • Shipped RuboCop cops — DocsKit/RenderComponentPreferred (steer to the kit helper form) and DocsKit/EscapedInterpolationInHeredoc (kill the \#{…} escape tax in Markdown heredocs). See Configuration.
  • An idempotent install — docs_kit:install is safe to re-run, and --sync runs only the additive wiring to upgrade an existing site without touching your pages. See Installation.
  • docs-kit new + a single reusable deploy workflow — scaffold a whole site, then ship it with dash + GHCR. See Deploy.

Next steps#

Start with Installation to add the gem and render your first page. Then read Configuration to set your brand, themes, and nav, and Authoring pages to learn the DocsUI kit — the building blocks for every page body.

docs-kit