# Authoring Hep.gg Docs with an AI assistant

You are editing a Hep.gg documentation site ("Docs"). This guide tells you how
the content is organized, every component you can use in markdown, and the HTTP
API to read the current pages and write new ones. Follow it to generate or edit
a full site in one pass.

## Authentication

Every request needs a site key in the Authorization header:

    Authorization: Bearer <KEY>

There are two kinds, both scoped to ONE site:
- One-off editing keys start with `dpk_` and expire about an hour after the
  owner generates one in the dashboard. Use these for a single working session.
- Long-lived keys start with `hepgg_docs_` and are for scripts/CI.

Base URL: https://hep.gg/api/v1/pages

## The content model

A site is a tree of markdown pages plus optional category metadata.

- A documentation page has a path like `docs/<folder>/<name>`. Its public URL
  is `/` + that path, e.g. `docs/guides/install` serves at `/docs/guides/install`.
- The first segment is always `docs`. Folders become sidebar categories.
- A page's order in the sidebar comes from its `sidebar_position` frontmatter
  (lower = higher). A category's order/label come from a category record (see
  POST /ai/category).
- Standalone pages (not in the doc sidebar) use a `pages/<name>` path and serve
  at `/<name>`.

### Frontmatter

Every page body may begin with YAML frontmatter:

    ---
    title: Installing the CLI
    description: One-line summary used in search + the LLM index.
    sidebar_label: Install
    sidebar_position: 2
    ---

Fields: `title`, `description`, `sidebar_label`, `sidebar_position` (number),
`hide_title` (bool), `draft` (bool).

### Page format

Pass `format: "mdx"` (default) to use the components below, or `format: "md"`
for plain CommonMark + GFM with no components. You may NOT use raw HTML script,
imports, exports, or `{javascript}` expressions; they are stripped. Only the
components listed here are available.

## HTTP API

- `GET /ai/site` -> the site summary + a list of every page (path, title, format).
  Call this first to see what exists.
- `GET /ai/page?path=docs/guides/install` -> { path, format, frontmatter, body, llmBody }.
- `PUT /ai/page` (JSON) -> create or replace a page:

      { "path": "docs/guides/install",
        "format": "mdx",
        "frontmatter": { "title": "Install", "sidebar_position": 2 },
        "body": "# Install\n\n..." }

  `path` must start with `docs/` or `pages/` (no file extension). `llmBody` is
  optional plain-markdown for the page's machine twin (served under /llms).
- `DELETE /ai/page?path=docs/guides/old` -> remove a page.
- `POST /ai/category` (JSON) -> set a folder's sidebar label/order:

      { "path": "docs/guides", "label": "Guides", "position": 1, "collapsed": false }

Responses use `{ "ok": true, "data": ... }` or `{ "ok": false, "error": "...", "code": "..." }`.

## Components (use inside body, format "mdx")

### Admonitions (free)
Callout boxes. Six types: note, tip, info, warning, caution, danger.

    :::tip Optional custom title
    Helpful aside text. Markdown works inside.
    :::

### Cards and grids (free)
Link tiles, optionally in a grid.

    <CardGrid cols="3">
    <Card title="Quickstart" icon="Rocket" href="/docs/quickstart">Get running in 5 minutes.</Card>
    <Card title="API" icon="Terminal" href="/docs/api/overview">Every endpoint, with examples.</Card>
    </CardGrid>

`icon` is one of a fixed Lucide set (e.g. Rocket, Terminal, Upload, Database,
Mail, KeyRound, Globe, Sparkles, ShieldCheck, FileText). Unknown icons fall back.

### API reference blocks (free)
Document an endpoint.

    <Method method="POST" /> a coloured HTTP verb badge, inline.

    <Endpoint method="POST" path="/api/v1/things/:id" baseUrl="https://api.example.com" auth="required" summary="Create a thing." id="create-thing" />

    <Params title="Body">
    <Param name="name" type="string" required>The thing's name.</Param>

    <Param name="count" type="number" default="1">How many.</Param>
    </Params>

Leave a blank line between `<Param>` rows.

### WhereItLives (free)
States a base URL for a section.

    <WhereItLives host="https://api.example.com">All endpoints below live here.</WhereItLives>

### Code groups (free)
Tabbed code samples. Give each fenced block a `title`.

    <CodeGroup labels="curl,node">

    ```bash title="curl"
    curl https://api.example.com/things
    ```

    ```js title="node"
    await fetch("https://api.example.com/things")
    ```

    </CodeGroup>

### Tabs and Steps (free)

    <Tabs labels="macOS,Linux">
    <TabItem>brew install x</TabItem>

    <TabItem>apt install x</TabItem>
    </Tabs>

    <Steps>
    <Step title="Install">Run the installer.</Step>

    <Step title="Configure">Edit the config file.</Step>
    </Steps>

### Premium components
These render only on sites whose owner has Hep.gg Prime; on a free site they
show a small "Prime" notice instead. Prefer the free components unless the site
is premium.

- `<Accordion>` / `<AccordionItem title="...">` - collapsible sections.
- `<Embed src="https://..." />` - an embedded video/iframe by URL (no uploads;
  the owner embeds media by URL).
- `<Callout color="...">...</Callout>` - a custom-coloured callout.

## Images and media

Do NOT attempt to upload images. Reference images and media by URL only
(`![alt](https://...)`). The owner uploads files to their Hep.gg uploader and
pastes the URL.

## A good site

Start with `GET /ai/site`. Create a short `docs/overview` (or `docs/intro`) as
the landing page, group related pages into folders, set category labels/order
with POST /ai/category, write clear `description` frontmatter on every page (it
powers search and the LLM index), and keep one idea per sentence. When done,
tell the owner to publish the site and mount a domain from their dashboard.