Skip to content

Commit 68751af

Browse files
bmuenzenmeyeravivkellerclaude
authored
feat(docs): add documentation for doc-kit (#889)
* setup CICD * adds doc kit docs * reminds people that target can be supplied by config, not just flags * promote every heading up a level to make doc-kit rendering easier per the spec * fix lint * improve home page content, making sure to format pages * slight tweaks to getting started * use node directly rather than npm * improve documentation based on feedback * add showcase * Update www/pages/index.md Co-authored-by: Aviv Keller <me@aviv.sh> * Update scripts/vercel-docs-build.sh Co-authored-by: Aviv Keller <me@aviv.sh> * Update www/pages/getting-started.md Co-authored-by: Aviv Keller <me@aviv.sh> * Update www/pages/index.md Co-authored-by: Aviv Keller <me@aviv.sh> * Update www/pages/getting-started.md Co-authored-by: Aviv Keller <me@aviv.sh> * Update www/pages/index.md Co-authored-by: Aviv Keller <me@aviv.sh> * format after reviews * better consistency * Update www/pages/getting-started.md Co-authored-by: Aviv Keller <me@aviv.sh> * adds files entries CHANGELOG, LICENSE, README are usually defaults, but i want to be affirmative here * fix(url): resolve parent-path targets in relative() relative() consumed the target's final path segment as a common directory whenever the target was a path prefix of the current page, so relative('/generators', '/generators/web') returned '.' instead of '../generators' — which callers appending '.html' turned into a broken '..html' link. Treat the last segment of `to` as the target itself so it always survives into the result. Unreachable in flat page layouts (every existing call site passes top-level paths, where the stripping loop never runs), so output is unchanged for those; surfaced by sites feeding nested input directories to the web generator. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * refactor doc-kit docs page creation --------- Co-authored-by: Aviv Keller <me@aviv.sh> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent 4534824 commit 68751af

31 files changed

Lines changed: 650 additions & 46 deletions

File tree

‎.changeset/fix-relative-parent-path.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
'@node-core/doc-kit': patch
3+
---
4+
5+
Fix `relative()` URL resolution when the target path is a prefix of the current
6+
page's path (e.g. `/generators` from `/generators/web`): the target's final
7+
segment was consumed as a common directory, producing `.` instead of
8+
`../generators`. Unreachable in flat page layouts; surfaced by sites with
9+
nested input directories.

‎.github/workflows/docs.yml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Documentation Site
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
concurrency:
11+
group: ${{ github.workflow }}-${{ github.ref }}
12+
cancel-in-progress: true
13+
14+
permissions:
15+
contents: read
16+
17+
jobs:
18+
build:
19+
name: Build docs site
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Harden Runner
23+
uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
24+
with:
25+
egress-policy: audit
26+
27+
- name: Git Checkout
28+
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
29+
with:
30+
persist-credentials: false
31+
32+
- name: Setup Node.js
33+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
34+
with:
35+
node-version-file: '.nvmrc'
36+
cache: 'npm'
37+
38+
- name: Install dependencies
39+
run: npm ci
40+
41+
- name: Build site
42+
run: node --run docs:build
43+
44+
- name: Upload site artifact
45+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
46+
with:
47+
name: docs-site
48+
path: www/out

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ npm-debug.log
66
out
77
base
88

9+
# Docs site content, assembled by scripts/build-docs-content.mjs
10+
www/content
11+
912
# Tests
1013
coverage
1114
junit.xml

‎.prettierignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ src/generators/web/template.html
1010
# Output
1111
out/
1212

13+
# Docs-site content, assembled by scripts/build-docs-content.mjs
14+
www/content/
15+
1316
# Generated Files
1417
src/generators/metadata/maps/mdn.json
1518

‎.prettierrc.json‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,5 +7,13 @@
77
"trailingComma": "es5",
88
"bracketSpacing": true,
99
"bracketSameLine": false,
10-
"arrowParens": "avoid"
10+
"arrowParens": "avoid",
11+
"overrides": [
12+
{
13+
"files": "www/pages/**/*.md",
14+
"options": {
15+
"proseWrap": "always"
16+
}
17+
}
18+
]
1119
}

‎docs/configuration.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ Configuration files can be either:
1616

1717
```javascript
1818
export default {
19+
// targets, alternatively supplied by command line flags
20+
target: ['orama-db', 'web'],
1921
global: {
2022
version: '20.0.0',
2123
minify: true,

‎package.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
"prepare": "husky || exit 0",
2222
"run": "node bin/cli.mjs",
2323
"watch": "node --watch bin/cli.mjs",
24+
"docs:build": "bash scripts/vercel-docs-build.sh",
2425
"changeset": "changeset",
2526
"changeset:version": "changeset version",
2627
"release": "changeset publish"
@@ -29,6 +30,16 @@
2930
"bin": {
3031
"doc-kit": "./bin/cli.mjs"
3132
},
33+
"files": [
34+
"src",
35+
"!src/**/*.test.mjs",
36+
"!src/**/__tests__",
37+
"bin",
38+
"shiki.config.mjs",
39+
"CHANGELOG.md",
40+
"LICENSE",
41+
"README.md"
42+
],
3243
"devDependencies": {
3344
"@changesets/changelog-github": "^0.7.0",
3445
"@changesets/cli": "^2.31.0",

‎scripts/build-docs-content.mjs‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
#!/usr/bin/env node
2+
3+
// Assembles `www/content/` — the input tree for the doc-kit documentation
4+
// site — from three sources that live elsewhere in the repo:
5+
//
6+
// www/pages/*.md authored narrative pages, copied verbatim
7+
// docs/*.md the existing reference docs
8+
// src/generators/*/README.md per-generator config reference, written to
9+
// `generators/<name>.md`
10+
//
11+
// `www/content/` is a build artifact and is gitignored. Run this before
12+
// invoking the `web` generator against it.
13+
14+
import { glob, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
15+
import { basename, dirname, join } from 'node:path';
16+
17+
const ROOT = join(import.meta.dirname, '..');
18+
const CONTENT = join(ROOT, 'www', 'content');
19+
20+
const SOURCES = [
21+
{ pattern: 'www/pages/*.md', rename: basename },
22+
{ pattern: 'docs/*.md', rename: basename },
23+
{
24+
pattern: 'src/generators/*/README.md',
25+
rename: file => `generators/${basename(dirname(file))}.md`,
26+
},
27+
];
28+
29+
/**
30+
* Collects the `{ name, markdown }` pages to write into `www/content/`.
31+
*
32+
* @returns {Promise<Array<{ name: string, markdown: string }>>}
33+
*/
34+
const collectPages = async () => {
35+
const groups = await Promise.all(
36+
SOURCES.map(async ({ pattern, rename }) => {
37+
const files = await Array.fromAsync(glob(pattern, { cwd: ROOT }));
38+
39+
return Promise.all(
40+
files.sort().map(async file => ({
41+
name: rename(file),
42+
markdown: await readFile(join(ROOT, file), 'utf-8'),
43+
}))
44+
);
45+
})
46+
);
47+
48+
return groups.flat();
49+
};
50+
51+
const pages = await collectPages();
52+
53+
await rm(CONTENT, { recursive: true, force: true });
54+
55+
await Promise.all(
56+
[...new Set(pages.map(({ name }) => dirname(join(CONTENT, name))))].map(dir =>
57+
mkdir(dir, { recursive: true })
58+
)
59+
);
60+
61+
await Promise.all(
62+
pages.map(({ name, markdown }) => writeFile(join(CONTENT, name), markdown))
63+
);
64+
65+
console.log(`Wrote ${pages.length} pages to www/content/`);

‎scripts/vercel-docs-build.sh‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
#!/usr/bin/env bash
2+
3+
# Build the doc-kit documentation site into `www/out/`.
4+
5+
node scripts/build-docs-content.mjs
6+
7+
node bin/cli.mjs generate \
8+
--config-file ./www/doc-kit.config.mjs \
9+
--log-level debug

‎src/generators/addon-verify/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
## `addon-verify` Generator
1+
# `addon-verify` Generator
22

33
The `addon-verify` generator extracts code blocks from `doc/api/addons.md` and generates a file list to facilitate C++ compilation and JavaScript runtime validations for Node.js addon examples.
44

5-
### Configuring
5+
## Configuring
66

77
The `addon-verify` generator accepts the following configuration options:
88

0 commit comments

Comments
 (0)