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

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)

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

In this directory:

cd docs
gem install bundler
bundle install

rbenv

Install rbenv and ruby-build, then rbenv install the version you need.
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 gem (see Gemfile). It provides the VitePress-like shell (sidebar, local nav, search, dark mode). Upstream docs: 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.

Create a new empty repository (e.g. myorg/kb-docs).
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.
In the KB product repo, publish into a checkout of that docs repo:
```
kb publish jekyll --apply --dir /path/to/kb-docs-clone
```
Commit and push from the docs repo when you are ready to deploy.
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

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:

Wrong host path — always use http://localhost:4000/kb/... when baseurl is /kb.
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.