# loopy-loop docs site

The public documentation for [loopy-loop](https://github.com/writeitai/loopy-loop),
published at **[loopy.writeit.ai](https://loopy.writeit.ai)**.

It is a self-contained static site: a Next.js App-Router app whose pages are authored
as MDX, exported to static HTML, and served by GitHub Pages. See
[`design/designs/documentation-site.md`](../design/designs/documentation-site.md) for
the decisions behind the stack.

## Stack

- **Next.js** (App Router) with **`@next/mdx`** — each `src/app/docs/**/page.mdx` file
  is a route.
- **Tailwind v4** + **`@tailwindcss/typography`** for prose, themed to the WriteIt
  brand palette in `src/app/globals.css`.
- **`rehype-pretty-code`** (Shiki) code highlighting, **`rehype-slug`** heading
  anchors, **`remark-gfm`**.
- **Pagefind** static search surfaced through a **`cmdk`** ⌘K command palette.
- `output: 'export'` → fully static; no server.

## Develop

```bash
cd website
npm install
npm run dev        # http://localhost:3000
```

> Search (⌘K) only returns results in a production build — the Pagefind index is
> generated by `postbuild`, so it is absent during `npm run dev`.

## Build

```bash
npm run build      # next build (-> out/) then pagefind indexes out/
```

The static site is written to `website/out/`. Preview that production build (with
a working search index) via `npm run preview`. `npm run typecheck` runs `tsc
--noEmit` — run it after a build, since it depends on Next's generated types.

## Add or edit a page

1. Create `src/app/docs/<route>/page.mdx`. Start it with an exported `metadata`
   object (`title`, `description`), then a single `#` H1, then content. Use `##`/`###`
   headings — they populate the "On this page" table of contents.
2. Add the page to `src/lib/docs/navigation.ts`. That array is the single source of
   truth for the sidebar order and prev/next pagination.

## Deploy

`.github/workflows/docs-deploy.yml` builds and deploys to GitHub Pages on every push
to `main` that touches `website/**` (pull requests run the build as a check only).
`public/.nojekyll` keeps GitHub Pages from stripping Next's `_next/` assets.

### One-time setup (required before the first deploy)

The workflow publishes the artifact, but the Pages site and its custom domain must be
provisioned once in the repository — the `public/CNAME` file does **not** configure the
domain on its own for an Actions-based deployment:

1. **Settings → Pages → Build and deployment → Source:** select **GitHub Actions**.
2. **Settings → Pages → Custom domain:** enter `loopy.writeit.ai` and save (this is
   what actually binds the domain; the committed `CNAME` file just records the intent).
3. **DNS** (in the `writeit.ai` zone): add `loopy.writeit.ai CNAME writeitai.github.io.`
4. Once DNS resolves, enable **Enforce HTTPS** in Settings → Pages.

Until the custom domain is bound, the site would be served under
`https://writeitai.github.io/loopy-loop/`, where the root-relative `/_next/` and
`/pagefind/` URLs do not resolve — so complete the steps above before sharing the link.
