Getting started

Installation

Scaffold a new docs site in one command, add docs-kit to an existing Rails app, or re-run the generator with --sync to upgrade.

New site in one command#

The fastest path — a deployable app from scratch.

docs-kit new my-docs --image OWNER/REPO --service my-repo

This runs rails new (propshaft + importmap + turbo/stimulus, no database) and applies the docs-kit template, which:

adds the gem and its dependencies,
runs the install generator,
syncs the lucide icons,
builds the Tailwind CSS, and
scaffolds the dash deploy.

Then boot it:

cd my-docs && bin/dev

The generator path (docs-kit new) performs every step in the “Add to an existing Rails app” section below automatically. Reach for the manual steps only when adding docs-kit to an app you already have.

Add to an existing Rails app#

Four steps: the gems, the generator, the icons, the CSS.

1. Add the gems.

Gemfile

gem "docs-kit"
gem "daisyui", require: "daisy_ui"
gem "phlex-rails"
gem "rails_icons", "~> 1.1"
gem "rouge"

Then run bundle install.

2. Run the install generator.

rails g docs_kit:install

It is fully idempotent — safe on a fresh app AND a years-old site, so re-running it is the sanctioned upgrade path. File creations skip what already exists; the config initializer is never clobbered; routes are skipped even when the site wrote them in its own style.

The generator wires the following into your app:

What	Why
`config/initializers/docs_kit.rb`	The site config — brand, themes, nav. Skipped if present (never clobbered).
`config/initializers/phlex.rb`	Phlex autoload namespaces (Views::, Components::).
`config/initializers/rails_icons.rb`	The rails_icons config for the lucide chrome icons.
`app/models/doc.rb`	The Doc registry, seeded with a sample page.
`app/views/docs/pages/installation.rb`	A sample page to prove the render path.
`routes`	docs/:doc(.:format), the search / llms.txt / llms-full.txt routes, and a commented MCP route.
`bin/build-css + application.tailwind.css`	The Bun/Tailwind CSS build, carrying the theme @plugin block.
`controllers/index.js`	Registers the docs-nav Stimulus controller (eager-loaded).
`AGENTS.md + .claude skill`	The AI-authoring contract and a write-docs-page Claude Code skill.
`.rubocop.yml`	docs-kit's shipped cops, merged into an existing config.

The generator also injects include DocsKit::Controller into your ApplicationController — that is what provides the #render_page helper the docs controller calls.

3. Sync the icons.

rails g rails_icons:sync --library=lucide

4. Build the CSS.

bun install && bun run build:css

Then set your brand, themes, and nav in config/initializers/docs_kit.rb — see Configuration for every knob — and write your first page (see Authoring pages).

Upgrade an existing site#

rails g docs_kit:install --sync pulls new wiring without touching your content.

docs-kit ships new wiring over time — new routes, a new Stimulus registration, updated AGENTS.md guidance, RuboCop cops. To pull those into an existing site, re-run the generator with --sync. This is the sanctioned upgrade path.

rails g docs_kit:install --sync

--sync is additive. It runs ONLY the idempotent wiring steps and scaffolds no content:

Runs the routes, the initializer hint, the importmap/Stimulus registration, the AGENTS.md block, and the .rubocop.yml cops.
Skips everything you own — the Doc registry, your pages, and the application.tailwind.css build. Those already exist and are yours to edit, so a sync never touches them.

A sync also prints a drift report — manual cleanup it detects but won't do for you, because it can't safely automate a delete. It warns, never deletes, and never fails the run. The two items it looks for:

Drift	What to do
`A hand-rolled render_page`	app/controllers/application_controller.rb defines its own #render_page — DocsKit::Controller already provides it, so the copy shadows the gem's. Delete it.
`A dead IconHelper`	app/helpers/icon_helper.rb is dead code — docs-kit renders icons via rails_icons (DocsUI::Icon). Delete it.

After a sync: run bun run build:css to pick up any new emitted classes, then bundle exec rspec to confirm the site still boots and renders.

Requirements#

Requirement	Version/Note
`Ruby`	>= 3.2
`Rails`	>= 7.1
`Bun`	for the Tailwind CSS build
`PostgreSQL`	not required (docs sites are stateless)

Verify#

Boot the app with bin/dev and visit /docs. You should see the shell with the sidebar, the theme switcher, and this page's content.