---
type: CLI Command
title: okforge webview
description: Generate or serve a static website that bakes an OKF bundle into a dependency-free site.
resource: src/commands/webview_command.ts
tags: [cli, webview, static-site, serve]
timestamp: 2026-07-03
---

# Synopsis

```bash
npx okforge webview generate [bundle] [-o <dir>]
npx okforge webview show [bundle]
```

Renders an OKF bundle as a static website — concept pages with rendered
markdown and link panels, an overview dashboard, an interactive concept graph,
and search. The generated output has no runtime dependencies and opens directly
from `file://`. Both subcommands are implemented by `WebviewCommand`
(`src/commands/webview_command.ts`), which reuses
[OkfGraph](../runtime_concepts/okf_graph.md) so the site stays consistent with
[graph](./graph.md) and [check](./check.md).

# Subcommands

## generate

| Argument / option | Default | Meaning |
| --- | --- | --- |
| `[bundle]` | `.okf` | OKF bundle root: a local directory **or** an http(s) URL. |
| `-o, --output_folder <dir>` | `okforge_webview` | Output directory for the static site. |

Bakes the bundle's graph metadata and raw markdown into `<output>/data.js`
(`window.__OKF__`), then copies the static app template alongside it. Prints the
generated `index.html` path, the bundle source, the concept count, and the
broken-link count.

## show

| Argument | Default | Meaning |
| --- | --- | --- |
| `[bundle]` | `.okf` | OKF bundle root: a local directory **or** an http(s) URL. |

Generates the site into a temp directory, then serves it over HTTP on an
ephemeral `http://127.0.0.1:<port>/` address until interrupted with Ctrl-C.

# URL bundle sources

When `[bundle]` is an http(s) URL it is downloaded into a temp directory first by
[OkfFetch](../runtime_concepts/okf_fetch.md) and then treated as a local bundle,
so a published bundle can be rendered without cloning it. A GitHub
`tree` URL (`https://github.com/<owner>/<repo>/tree/<ref>/<path>`) is rewritten
to its `raw.githubusercontent.com` equivalent as a convenience.

```bash
npx okforge webview show https://github.com/jeromeetienne/okforge/tree/main/.okf
```

# How it works

`WebviewCommand` (`src/commands/webview_command.ts`):

1. Resolves the bundle source with `resolveBundle` — a local directory is used in
   place; an http(s) URL is downloaded into a temp directory first by
   [OkfFetch](../runtime_concepts/okf_fetch.md) and then treated as local.
2. Builds the bundle graph with `OkfGraph.build(root)`.
3. **Bakes** every concept node into a `BakedConcept` (graph metadata plus the
   raw markdown body read from disk) and every reserved file (`index.md`,
   `log.md`) into a `reserved` map keyed by bundle path.
4. Computes an `overview` mirroring `okforge graph overview` (concept count,
   per-folder groups, top-10 hubs, orphans, broken links).
5. Copies the static app template (`src/webview/template/`) verbatim into the
   output and writes the data island to `data.js` as `window.__OKF__ = { ... }`.

The browser app (`template/app.js`, `index.html`, `styles.css`,
`vendor/marked.min.js`) reads `window.__OKF__` — nothing is fetched at runtime.

# Baked data shape

`window.__OKF__` (`BakedData`):

| Field | Meaning |
| --- | --- |
| `root` | Display name of the bundle (basename for a local path, last URL segment for a URL). |
| `generatedAt` | ISO 8601 generation timestamp. |
| `concepts` | Array of `BakedConcept`, sorted by `id`. |
| `reserved` | Raw bodies of `index.md` / `log.md`, keyed by bundle path. |
| `overview` | Concept count, groups, hubs, orphans, broken links. |

`BakedConcept` fields: `id`, `file`, `group` (top-level folder, `<root>` for
root concepts), `type`, `title`, `description`, `tags`, `outbound`, `inbound`,
`broken`, `markdown`.

# Build and deploy

The static app template lives in `src/webview/template/` and is copied verbatim
into every generated site; its own README is [`src/webview/README.md`](../../src/webview/README.md).
GitHub Pages publishing runs through repo-root `package.json` convenience
scripts:

| Script | Action |
| --- | --- |
| `npm run webview:build` | `tsx src/cli.ts webview generate .okf -o webview_dist` — render `./.okf` into `webview_dist/` (gitignored). |
| `npm run webview:open` | Build, then open `webview_dist/index.html`. |
| `npm run webview:deploy` | Build, then run `scripts/webview_deploy.sh` to force-push `webview_dist/` to the `gh-pages` branch as a single fresh commit (with a `.nojekyll` marker). |

# Citations

- [`src/commands/webview_command.ts`](../../src/commands/webview_command.ts)
- [`src/cli.ts`](../../src/cli.ts)
- [`src/misc/okf_fetch.ts`](../../src/misc/okf_fetch.ts)
- [`src/webview/template/`](../../src/webview/template/)
- [`src/webview/README.md`](../../src/webview/README.md)
- [`scripts/webview_deploy.sh`](../../scripts/webview_deploy.sh)
