# KB Jekyll Site

This directory is the Jekyll source for the **kb dogfood** documentation site, published to GitHub Pages at `https://rosenjcb.github.io/kb`.

> **Eval runs publish to a separate site.** The canonical evaluation target is `~/raylib/`. Its Jekyll output goes to `~/raylib-kb-docs/` — never here. See `EVALUATION.md` for details.

## How it works

`kb publish jekyll --base dogfood --dir docs/ --apply` (run from the repo root) syncs the dogfood knowledge base into this directory:

- `_original_docs/` — raw source files collected during `kb init` (READMEs, CLAUDE.md, etc.)
- `_autogenerated_docs/` — LLM-synthesized documents produced by `kb init`
- `_data/kb_original_docs.yml` — generated index of original docs (title → URL)
- `_data/kb_autogenerated_docs.yml` — generated index of autogenerated docs

**Do not edit files in `_original_docs/` or `_autogenerated_docs/` by hand** — they are overwritten on every publish.

## Prerequisites

The Jekyll site depends on static config that must already exist in this directory before publish runs:

| File | Purpose |
|------|---------|
| `_config.yml` | Jekyll site config, collections, theme settings |
| `_data/sidebar.yml` | Sidebar navigation groups |
| `_data/navigation.yml` | Top nav bar |
| `index.md` | Homepage |

These files are checked into git and are not overwritten by `kb publish jekyll`.

## Ruby environment (chruby, rbenv, or system Ruby)

Jekyll 4.x runs on Ruby. Pick one workflow and stay consistent in CI and on your laptop.

### chruby + ruby-install (macOS / Linux)

1. Install [homebrew](https://brew.sh/) if needed, then `ruby-install` and `chruby` (exact package names vary by OS; on macOS many people use `brew install chruby ruby-install`).
2. Install a supported Ruby (see `docs/Gemfile` / `.ruby-version` if present), e.g. `ruby-install ruby 3.3 -- --enable-shared`.
3. Configure your shell to `source` chruby’s `auto.sh` and set a default Ruby.
4. In this directory:

   ```bash
   cd docs
   gem install bundler
   bundle install
   ```

### rbenv

1. Install rbenv and ruby-build, then `rbenv install` the version you need.
2. `cd docs && rbenv local <version> && gem install bundler && bundle install`.

### Bundler and native gems

`jekyll` and `sass-embedded` pull native extensions. If `bundle install` fails, install your platform’s build toolchain (Xcode CLT on macOS, `build-essential` on Debian/Ubuntu), then retry.

## VitePress-style theme (`jekyll-vitepress-theme`)

This site uses the [`jekyll-vitepress-theme`](https://github.com/crmne/jekyll-vitepress-theme) gem (see `Gemfile`). It provides the VitePress-like shell (sidebar, local nav, search, dark mode). Upstream docs: [jekyll-vitepress.dev](https://jekyll-vitepress.dev/).

Minimal pieces you need in `_config.yml` (already mirrored here):

- `theme: jekyll-vitepress-theme` and `plugins: [jekyll-vitepress-theme]`
- A `jekyll_vitepress:` block for branding, syntax highlighting, footer, GitHub star button, etc.
- **Collections** with `output: true` and a stable `permalink` (this repo uses `/:name.html` per doc basename).
- **`baseurl`** set to your GitHub Pages project path (here `/kb`) so asset and page URLs resolve under `https://<user>.github.io/kb/`.

After `bundle install`, `bundle exec jekyll serve` prints the correct URL including `baseurl` (see below).

## Keeping `docs/` in a separate repo

Many teams split “product code” and “docs site” so the marketing/docs repo has its own issues and Pages deploy.

1. Create a new empty repository (e.g. `myorg/kb-docs`).
2. Copy or scaffold this `docs/` layout: `Gemfile`, `_config.yml`, `_layouts` from the theme (usually inherited via the gem), `_data/sidebar.yml`, `_data/navigation.yml`, `index.md`, `404.html`, and the same **collection names** (`original_docs`, `autogenerated_docs`, optional `handbook`) so `kb publish jekyll` output matches what the theme and sidebar expect.
3. In the **KB product** repo, publish into a checkout of that docs repo:

   ```bash
   kb publish jekyll --apply --dir /path/to/kb-docs-clone
   ```

   Commit and push from the docs repo when you are ready to deploy.

4. Point GitHub Actions (or Pages branch) at the docs repo root where `_config.yml` lives.

`_config.yml` in the docs repo should set `url` and `baseurl` to match that site’s GitHub Pages URL pattern.

## Local preview

```bash
cd docs
bundle install
bundle exec jekyll serve
```

Open the URL Jekyll prints (with this config it is **`http://127.0.0.1:4000/kb/`** — note the **`/kb/`** prefix matching `baseurl`). Requests to `/claude.html` without the prefix will 404.

## Troubleshooting

### Collection links 404 (`/kb/foo.html` not found)

Common causes:

1. **Wrong host path** — always use `http://localhost:4000/kb/...` when `baseurl` is `/kb`.
2. **Stale `_site`** — delete `docs/_site` and rebuild if you switched branches or configs.

YAML **`date`** on published pages is the **local calendar day** of the publish run (date only — no clock time), not SQLite `created_at`. That avoids Jekyll treating UTC-ish timestamps as “future” vs `site.time` and skipping HTML. `future: true` is also set so collection output is never suppressed for date quirks. These are static doc pages, not a blog chronology.

### Theme writes `.md` next to missing `.html`

`jekyll-vitepress-theme` adds a `post_write` hook that mirrors each rendered page as raw Markdown under `_site` for “copy page”. That is normal; the HTML file must still exist for the browser route.

## Deploy

GitHub Actions builds and deploys on pushes that touch this site; see `.github/workflows/jekyll-docs.yml`.