# Documentation Sites



<a id="section-goal"></a>

A Context documentation site is a static website built from the same approved knowledge as your knowledge package. Turn it on with a `site` option on the package; every `context build` then writes the package and a sibling `dist/<base>-site/` folder you can preview locally and upload to any static host.

```mermaid
flowchart LR
  map["src/knowledge-map.yaml"] --> build["context build"]
  approved["Approved knowledge"] --> build
  ext["src/site/ (optional)"] --> build
  build --> site["dist/base-site/"]
  site --> preview["Local preview"]
  site --> host["Your static host"]
```


<a id="section-enable"></a>

## Turning it on

```ts
kbPackage({
  name: "project-kb",
  template: "src/package-templates/kb",
  site: {
    title: "Project knowledge",
    lang: "en-US",
    base: "/",
    home: {
      slogan: "Find the context behind the work",
      resources: [{
        title: "Project workspace",
        description: "Open the repository that maintains this knowledge.",
        href: "https://example.com/project",
        featured: true,
      }],
    },
  },
});
```

| Option | Meaning |
| --- | --- |
| `title`, `description` | Site title (defaults to the package name) and description |
| `lang` | Primary language, default `en-US` |
| `base` | URL prefix, default `/`; use `/docs/` when hosted under that path. It does not change output folders |
| `home` | Landing-page title, slogan, description and resource cards; each card needs a safe `href`, a copyable `command`, or both; `featured` also places it among the hero actions |

The output folder drops one trailing `-kb` from the package name: `project-kb` builds `dist/project-kb/` and `dist/project-site/`. Resource cards come from confirmed settings, repository remotes or real deployment results; unknown destinations are omitted, never filled with placeholders.


<a id="section-features"></a>

## What the site offers

- **Homepage** — every first-level knowledge-map section as a card with a bounded preview of its pages, plus LLM Docs and Changelog.
- **Navigation** — top-bar sections; the left sidebar shows only the current section's descendants.
- **Search** — local search, opened with the search button or Cmd/Ctrl+K; no search service.
- **Theme** — light and dark, following the operating system until the reader chooses; the choice is remembered and applied from the first paint, so pages do not flash the other scheme while loading.
- **Missing pages** — an unknown address shows a centred 404 page in the reader's language with a link back to the site home.
- **Diagrams** — Mermaid rendered in the browser with fit, 100%, zoom, full-screen and source controls. Invalid diagrams keep their source with a notice instead of blocking publication.
- **Provenance** — each article ends with its sources: repository entries link to the recorded revision, document entries to their registered URL.

Code samples and raw HTML are displayed as content, never executed.



<a id="section-navigation"></a>

## Navigation comes from the knowledge map

`src/knowledge-map.yaml` decides the sidebar: each entry binds to an article by its identity, so labels and parent groups never change an article's URL, and one article can appear in several places while keeping one URL. Every selected article needs a valid place before packaging; missing bindings block the build and the CLI returns the list to place. Category entries may stay empty while articles are still planned.

| Setting | Adds |
| --- | --- |
| `site.nav` | Links after the reading sections in the top bar |
| `site.more` | Items in the More menu, before LLM Docs and Changelog; an item may target an approved article kept outside the map, such as release notes |
| `socialLinks` | Icon links in the top bar (`https` only) |
| `titleLink` | Where the site title leads; a root-relative link such as `/` addresses the origin, not `base` |

Links starting with `/` are origin paths, which lets a site under `/docs/` link to a sibling application on the same domain. `locales` on a nav or More item translates its label.


<a id="section-build"></a>

## Building and previewing

The site is generated in a staging folder before anything is replaced, so a failed website build keeps the previous package and site. Removing `site` deletes the old site on the next successful build. `dist/<base>-site/context-site-map.json` records each article's approved path, package path and site path, plus the menu and any unresolved targets.

Preview it through a local HTTP server:

```sh
python3 -m http.server 8000 --bind 127.0.0.1 --directory dist/project-site
```

The Agent's completion report lists the package folder, website folder and LLM text separately, each as generated, failed or not selected, with navigation coverage and the verified preview URL.


<a id="section-deploy"></a>

## Deploying

Deploy the **contents of `dist/<base>-site/`** with your chosen static hosting tool. Context's build includes no hosting SDK, login or deployment step; after every successful website build the Agent tells you which folder to deploy and, if you have authorized a target, uses a compatible deployment Skill. Only the website folder is published — never sources, private workspace state or the whole package — and success is reported only after the hosted URL is checked.

Once deployed, record the public root so query Skills can link to pages:

```bash
context package site-url project-kb https://example.com/docs/
```

The address is an access hint, not proof of publication; rebuilds keep it.

| You ask for | The Agent does |
| --- | --- |
| Package and website | One `kbPackage` with `site` |
| Package only | Removes `site` and rebuilds; the old site is deleted |
| Add a website later | Adds `site`, places any unplaced articles, rebuilds |
| Website only for sharing | Builds the package too, shares only the website folder |

To change pages, slots and colors, see [Page and Theme Customization](</context/llms/pages/a14f7cbf6856dbd2ae309934ea6186c8.txt>); for other languages, [Multilingual Sites](</context/llms/pages/c1dc07fb24e9ea500fee02e9e275f4b7.txt>).

---

## Sources

- [context/packages/context/docs/guides/package-outputs.md L39–L54 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L39-L54>)
- [context/packages/context/docs/guides/package-outputs.md L183–L187 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L183-L187>)
- [context/packages/context/docs/guides/package-outputs.md L56–L87 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L56-L87>)
- [context/packages/context/docs/guides/package-outputs.md L89–L95 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L89-L95>)
- [context/packages/context/docs/guides/package-outputs.md L97–L121 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L97-L121>)
- [context/CHANGELOG.md L10–L14 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/CHANGELOG.md#L10-L14>)
- [context/packages/context-cli/src/project/packageSiteTheme.ts L329–L334 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context-cli/src/project/packageSiteTheme.ts#L329-L334>)
- [context/packages/context/docs/guides/package-outputs.md L123–L150 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L123-L150>)
- [context/packages/context/docs/guides/page-customization.md L37–L40 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/page-customization.md#L37-L40>)
- [context/packages/context/docs/guides/package-outputs.md L167–L182 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L167-L182>)
- [context/packages/context/docs/guides/package-outputs.md L454–L461 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L454-L461>)
- [context/packages/context/docs/guides/package-outputs.md L477–L497 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L477-L497>)
- [context/packages/context/docs/guides/package-outputs.md L533–L552 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L533-L552>)
- [context/packages/context/docs/guides/package-outputs.md L445–L452 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/package-outputs.md#L445-L452>)