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.

```shell
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:

```shell
cd my-docs && bin/dev
```

> **Tip:** 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.**

```ruby
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.**

```shell
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](#upgrade-an-existing-site). 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. |

> **Note:** 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.**

```shell
rails g rails_icons:sync --library=lucide
```

**4. Build the CSS.**

```shell
bun install && bun run build:css
```

Then set your brand, themes, and nav in `config/initializers/docs_kit.rb` — see [Configuration](https://docs-kit.zoolutions.llc/docs/configuration) for every knob — and write your first page (see [Authoring pages](https://docs-kit.zoolutions.llc/docs/authoring)).

## 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**.

```shell
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. |

> **Tip:** 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.