Skip to content

Commit acf914c

Browse files
avivkelleravivkeller
committed
add docs
1 parent 57d7dd0 commit acf914c

2 files changed

Lines changed: 41 additions & 10 deletions

File tree

‎src/generators/web/README.md‎

Lines changed: 40 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,17 @@ The `web` generator transforms JSX AST entries into complete web bundles, produc
66

77
The `web` generator accepts the following configuration options:
88

9-
| Name | Type | Default | Description |
10-
| ---------------- | -------- | --------------------------------------------- | --------------------------------------------------------------------- |
11-
| `output` | `string` | - | The directory where HTML, JavaScript, and CSS files will be written |
12-
| `templatePath` | `string` | `'template.html'` | Path to the HTML template file |
13-
| `project` | `string` | `'Node.js'` | Project name used in page titles and the version selector |
14-
| `title` | `string` | `'{project} v{version} Documentation'` | Title template for HTML pages (supports `{project}`, `{version}`) |
15-
| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links |
16-
| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links |
17-
| `imports` | `object` | See below | Object mapping `#theme/` aliases to component paths for customization |
18-
| `virtualImports` | `object` | `{}` | Additional virtual module mappings merged into the build |
9+
| Name | Type | Default | Description |
10+
| ----------------- | --------- | --------------------------------------------- | --------------------------------------------------------------------- |
11+
| `output` | `string` | - | The directory where HTML, JavaScript, and CSS files will be written |
12+
| `templatePath` | `string` | `'template.html'` | Path to the HTML template file |
13+
| `project` | `string` | `'Node.js'` | Project name used in page titles and the version selector |
14+
| `title` | `string` | `'{project} v{version} Documentation'` | Title template for HTML pages (supports `{project}`, `{version}`) |
15+
| `useAbsoluteURLs` | `boolean` | `false` | When `true`, all internal links use absolute URLs based on `baseURL` |
16+
| `editURL` | `string` | `'${GITHUB_EDIT_URL}/doc/api{path}.md'` | URL template for "edit this page" links |
17+
| `pageURL` | `string` | `'{baseURL}/latest-{version}/api{path}.html'` | URL template for documentation page links |
18+
| `imports` | `object` | See below | Object mapping `#theme/` aliases to component paths for customization |
19+
| `virtualImports` | `object` | `{}` | Additional virtual module mappings merged into the build |
1920

2021
#### Default `imports`
2122

@@ -60,6 +61,8 @@ All scalar (non-object) configuration values are automatically exported. The def
6061
| `versions` | `Array<{ url, label, major }>` | Pre-computed version entries with labels and URL templates (only `{path}` remains for per-page use) |
6162
| `editURL` | `string` | Partially populated "edit this page" URL template (only `{path}` remains) |
6263
| `pages` | `Array<[string, string]>` | Sorted `[name, path]` tuples for sidebar navigation |
64+
| `useAbsoluteURLs` | `boolean` | Whether internal links use absolute URLs (mirrors config value) |
65+
| `baseURL` | `string` | Base URL for the documentation site (used when `useAbsoluteURLs` is `true`) |
6366
| `languageDisplayNameMap` | `Map<string, string>` | Shiki language alias → display name map for code blocks |
6467

6568
#### Usage in custom components
@@ -96,3 +99,30 @@ The `Layout` component receives the following props:
9699
| `children` | `ComponentChildren` | Processed page content |
97100

98101
Custom Layout components can use any combination of these props alongside `#theme/config` imports.
102+
103+
### HTML template
104+
105+
The HTML template file (set via `templatePath`) uses JavaScript template literal syntax (`${...}` placeholders) and is evaluated at build time with full expression support.
106+
107+
#### Available template variables
108+
109+
| Variable | Type | Description |
110+
| ------------------ | -------- | ----------------------------------------------------------------- |
111+
| `title` | `string` | Fully resolved page title (e.g. `'File system \| Node.js v22.x'`) |
112+
| `dehydrated` | `string` | Server-rendered HTML for the page content |
113+
| `importMap` | `string` | JSON import map for client-side module resolution |
114+
| `entrypoint` | `string` | Client-side entry point filename with cache-bust query |
115+
| `speculationRules` | `string` | Speculation rules JSON for prefetching |
116+
| `root` | `string` | Relative or absolute path to the site root |
117+
| `metadata` | `object` | Full page metadata (frontmatter, path, heading, etc.) |
118+
| `config` | `object` | The resolved web generator configuration |
119+
120+
Since the template supports arbitrary JS expressions, you can use conditionals and method calls:
121+
122+
```html
123+
<title>${title}</title>
124+
<link rel="stylesheet" href="${root}styles.css" />
125+
<script type="importmap">
126+
${importMap}
127+
</script>
128+
```

‎src/generators/web/ui/types.d.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ declare module '#theme/config' {
2020
// From web configuration
2121
export const templatePath: Configuration['templatePath'];
2222
export const title: Configuration['title'];
23+
export const useAbsoluteURLs: Configuration['useAbsoluteURLs'];
2324

2425
// From config generation
2526
export const version: string;

0 commit comments

Comments
 (0)