diff --git a/.c8rc.json b/.c8rc.json index 49031d7d..8d0dd9fa 100644 --- a/.c8rc.json +++ b/.c8rc.json @@ -3,7 +3,7 @@ "exclude": [ "eslint.config.mjs", "**/fixtures", - "packages/legacy/src/legacy-html/assets", + "packages/node-legacy/src/legacy-html/assets", "packages/react/src/html/ui", "**/*.d.ts" ] diff --git a/.changeset/configurable-navigation.md b/.changeset/configurable-navigation.md index 869cdc5e..90876a5f 100644 --- a/.changeset/configurable-navigation.md +++ b/.changeset/configurable-navigation.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Add `web.navigation`, which supplies the sidebar groups (`navigation.sidebar`) diff --git a/.changeset/curvy-items-smile.md b/.changeset/curvy-items-smile.md index 7b9492b4..2c851b96 100644 --- a/.changeset/curvy-items-smile.md +++ b/.changeset/curvy-items-smile.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': minor +'@doc-kit/core': minor --- Discover and load configuration files with `cosmiconfig`. diff --git a/.changeset/did-you-know-that-the-world-is-round.md b/.changeset/did-you-know-that-the-world-is-round.md index b890a4ab..20eba00a 100644 --- a/.changeset/did-you-know-that-the-world-is-round.md +++ b/.changeset/did-you-know-that-the-world-is-round.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Close Orama search when the target link is on the same page diff --git a/.changeset/display-name-type-unions.md b/.changeset/display-name-type-unions.md index f4b2cdb1..f8687c82 100644 --- a/.changeset/display-name-type-unions.md +++ b/.changeset/display-name-type-unions.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Resolve unions and arrays of display-name types (`{HTTP/2 Headers Object | vm.Module}`, `{HTTP/2 Headers Object[]}`), and stop capturing prose such as `U+007B ({), and U+007D (}).` as a type annotation. diff --git a/.changeset/doc-kit-scope-move.md b/.changeset/doc-kit-scope-move.md index dd10cf1a..a2caef7d 100644 --- a/.changeset/doc-kit-scope-move.md +++ b/.changeset/doc-kit-scope-move.md @@ -1,8 +1,10 @@ --- -'@nodejs/doc-kit': major +'@doc-kit/core': major +'@doc-kit/cli': major --- -The doc-kit engine and CLI, previously published as `@node-core/doc-kit`, -are now published as `@nodejs/doc-kit`. The `@node-core/doc-kit` name now -contains only the Node.js-specific generators (`api-links`, `addon-verify`, -and `man-page`). +The doc-kit engine and CLI, previously published together as +`@node-core/doc-kit`, are now published as two packages: `@doc-kit/core` +(the engine) and `@doc-kit/cli` (the `doc-kit` command-line interface). +The `@node-core/doc-kit` name now contains only the Node.js-specific +generators (`api-links`, `addon-verify`, and `man-page`). diff --git a/.changeset/fix-relative-parent-path.md b/.changeset/fix-relative-parent-path.md index 7745c39b..c8d3c1e0 100644 --- a/.changeset/fix-relative-parent-path.md +++ b/.changeset/fix-relative-parent-path.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Fix `relative()` URL resolution when the target path is a prefix of the current diff --git a/.changeset/legacy-kitten-package.md b/.changeset/legacy-kitten-package.md index b38a21ca..7078c8b7 100644 --- a/.changeset/legacy-kitten-package.md +++ b/.changeset/legacy-kitten-package.md @@ -1,11 +1,11 @@ --- -'@nodejs/doc-kit-generator-legacy': major -'@nodejs/doc-kit': major +'@node-core/doc-kit-legacy': major +'@doc-kit/core': major --- The legacy-format generators (`legacy-html`, `legacy-html-all`, `legacy-json`, and `legacy-json-all`) now live in the new -`@nodejs/doc-kit-generator-legacy` package and are loaded via import specifiers such -as `@nodejs/doc-kit-generator-legacy/legacy-html`. The corresponding -`@nodejs/doc-kit/*` package exports have been removed. The CLI shorthand +`@node-core/doc-kit-legacy` package and are loaded via import specifiers such +as `@node-core/doc-kit-legacy/legacy-html`. The corresponding +`@doc-kit/core/*` package exports have been removed. The CLI shorthand names are unchanged. diff --git a/.changeset/monorepo-layout.md b/.changeset/monorepo-layout.md index 603f5bc6..fdaa6c35 100644 --- a/.changeset/monorepo-layout.md +++ b/.changeset/monorepo-layout.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Moved the package into a `packages/core` workspace. diff --git a/.changeset/node-kitten-package.md b/.changeset/node-kitten-package.md index 1fa974c2..ca0f1335 100644 --- a/.changeset/node-kitten-package.md +++ b/.changeset/node-kitten-package.md @@ -1,6 +1,6 @@ --- '@node-core/doc-kit': major -'@nodejs/doc-kit': major +'@doc-kit/core': major --- The Node.js-specific generators (`api-links`, `addon-verify`, and diff --git a/.changeset/opt-out-banners.md b/.changeset/opt-out-banners.md index 53f9497a..78a19bf0 100644 --- a/.changeset/opt-out-banners.md +++ b/.changeset/opt-out-banners.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': minor +'@doc-kit/core': minor --- Add banner opt-out diff --git a/.changeset/plain-defaults.md b/.changeset/plain-defaults.md index 56ae327b..804c0f90 100644 --- a/.changeset/plain-defaults.md +++ b/.changeset/plain-defaults.md @@ -1,6 +1,6 @@ --- -'@nodejs/doc-kit': patch -'@nodejs/doc-kit-generator-react': minor +'@doc-kit/core': patch +'@doc-kit/generator-react': minor --- Defaults are now project-neutral instead of Node.js-specific diff --git a/.changeset/react-kitten-package.md b/.changeset/react-kitten-package.md index 25b93ea9..7caa5714 100644 --- a/.changeset/react-kitten-package.md +++ b/.changeset/react-kitten-package.md @@ -1,12 +1,12 @@ --- -'@nodejs/doc-kit-generator-react': minor -'@nodejs/doc-kit': major +'@doc-kit/generator-react': minor +'@doc-kit/core': major --- The React/JSX-based generators (`html` — previously `web` —, `jsx-ast`, `llms-txt`, `sitemap`, and `orama-db`) now live in the new -`@nodejs/doc-kit-generator-react` package and are loaded via import specifiers such as -`@nodejs/doc-kit-generator-react/html`. The corresponding `@nodejs/doc-kit/*` +`@doc-kit/generator-react` package and are loaded via import specifiers such as +`@doc-kit/generator-react/html`. The corresponding `@doc-kit/core/*` package exports have been removed. The `web` generator is renamed to `html`: the CLI shorthand `web` keeps working as a deprecated alias, but the configuration key is now `html` instead of `web`. diff --git a/.changeset/riscv64-warning-spacing.md b/.changeset/riscv64-warning-spacing.md index 4b60d25e..7d1b36f7 100644 --- a/.changeset/riscv64-warning-spacing.md +++ b/.changeset/riscv64-warning-spacing.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Fix missing spaces in the riscv64 multithreading warning message, which diff --git a/.changeset/short-deprecation-links.md b/.changeset/short-deprecation-links.md index 7b38dc5c..42a130af 100644 --- a/.changeset/short-deprecation-links.md +++ b/.changeset/short-deprecation-links.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Use short `DEP` codes for deprecation heading anchors. diff --git a/.changeset/spaced-union-types.md b/.changeset/spaced-union-types.md index 1498134d..d9419214 100644 --- a/.changeset/spaced-union-types.md +++ b/.changeset/spaced-union-types.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Space union separators in type annotation values (`{string|URL}` is now rendered as `string | URL`). diff --git a/.changeset/specifier-generator-loading.md b/.changeset/specifier-generator-loading.md index e6ee7d58..00168cc8 100644 --- a/.changeset/specifier-generator-loading.md +++ b/.changeset/specifier-generator-loading.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': minor +'@doc-kit/core': minor --- Generators are now loaded dynamically by import specifier instead of a static diff --git a/.changeset/swc.md b/.changeset/swc.md index ec6c6c6e..c24f650a 100644 --- a/.changeset/swc.md +++ b/.changeset/swc.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Switches `oxc-parser` for `@swc/wasm`, since `oxc-parser` does not provide the needed bindings. diff --git a/.changeset/tidy-deprecations-smile.md b/.changeset/tidy-deprecations-smile.md index fa83f542..9b034473 100644 --- a/.changeset/tidy-deprecations-smile.md +++ b/.changeset/tidy-deprecations-smile.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Preserve deprecation codes in generated table-of-contents labels. diff --git a/.changeset/tidy-donuts-search.md b/.changeset/tidy-donuts-search.md index 30e045d4..b1f3788b 100644 --- a/.changeset/tidy-donuts-search.md +++ b/.changeset/tidy-donuts-search.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Sync the URL hash when following same-page search hits diff --git a/.changeset/vite-web-generator.md b/.changeset/vite-web-generator.md index 74f4838b..d37a0138 100644 --- a/.changeset/vite-web-generator.md +++ b/.changeset/vite-web-generator.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': minor +'@doc-kit/core': minor --- Make the `web` generator bundler-neutral through a custom adapter contract, diff --git a/.changeset/yes-i-did-know-that-thank-you.md b/.changeset/yes-i-did-know-that-thank-you.md index 370e2bef..7431cdaa 100644 --- a/.changeset/yes-i-did-know-that-thank-you.md +++ b/.changeset/yes-i-did-know-that-thank-you.md @@ -1,5 +1,5 @@ --- -'@nodejs/doc-kit': patch +'@doc-kit/core': patch --- Render markdown `code` snippets in the sidebar diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 65aee295..098be160 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -141,7 +141,7 @@ jobs: path: node - name: Build Node.js API docs - run: npx doc-kit generate -t web -i "./node/doc/api/assert.md" -o out --config-file ./e2e/doc-kit.config.mjs + run: npx @doc-kit/cli generate -t web -i "./node/doc/api/assert.md" -o out --config-file ./e2e/doc-kit.config.mjs - name: Install Playwright browsers run: npx playwright install --with-deps diff --git a/.github/workflows/generate.yml b/.github/workflows/generate.yml index 214ae5de..725fb117 100644 --- a/.github/workflows/generate.yml +++ b/.github/workflows/generate.yml @@ -149,7 +149,7 @@ jobs: /usr/bin/time \ --output out/benchmark.json \ --format '{"elapsedSeconds": %e, "userCpuSeconds": %U, "systemCpuSeconds": %S, "maxRssKiB": %M}' \ - node packages/core/bin/cli.mjs generate \ + node packages/cli/bin/cli.mjs generate \ -t ${{ matrix.target }} \ -i "${{ matrix.input }}" \ -o out \ diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 74e7ee8a..d345f0be 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -58,7 +58,7 @@ jobs: SLACK_ICON: https://github.com/nodejs.png?size=48 SLACK_TITLE: ':rocket: doc-kit Packages Published' SLACK_MESSAGE: | - :package: *Packages*: `nodejs/doc-kit` workspace () + :package: *Packages*: `nodejs/doc-kit` workspace () :bust_in_silhouette: *Published by*: ${{ github.triggering_actor }} :octocat: *Commit*: SLACK_USERNAME: nodejs-bot diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index faaf19da..5ef6224c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# `@nodejs/doc-kit` Contributing Guide +# `doc-kit` Contributing Guide -Thank you for your interest in contributing to the `@nodejs/doc-kit` project! We welcome contributions from everyone, and we appreciate your help in making this project better. +Thank you for your interest in contributing to the `doc-kit` project! We welcome contributions from everyone, and we appreciate your help in making this project better. ## Table of Contents @@ -29,7 +29,7 @@ Thank you for your interest in contributing to the `@nodejs/doc-kit` project! We ## Getting Started -The steps below will give you a general idea of how to prepare your local environment for the `@nodejs/doc-kit` project and general steps for getting things done and landing your contribution. +The steps below will give you a general idea of how to prepare your local environment for the `doc-kit` project and general steps for getting things done and landing your contribution. ### Prerequisites @@ -77,14 +77,22 @@ This repository is an npm workspaces monorepo. The root package is private and holds the shared tooling (linting, formatting, tests, changesets); every published package lives under `packages/`: -- `packages/core`: [`@nodejs/doc-kit`](packages/core) — the doc-kit engine and CLI -- `packages/legacy`: [`@nodejs/doc-kit-generator-legacy`](packages/legacy) — the legacy-format generators +- `packages/cli`: [`@doc-kit/cli`](packages/cli) — the doc-kit command-line interface +- `packages/core`: [`@doc-kit/core`](packages/core) — the doc-kit engine - `packages/node`: [`@node-core/doc-kit`](packages/node) — the Node.js-specific generators -- `packages/react`: [`@nodejs/doc-kit-generator-react`](packages/react) — the React/JSX-based generators +- `packages/node-legacy`: [`@node-core/doc-kit-legacy`](packages/node-legacy) — the Node.js legacy-format generators +- `packages/react`: [`@doc-kit/generator-react`](packages/react) — the React/JSX-based generators Everything else at the root supports the repo rather than shipping to npm: -`docs/` (the reference docs), `www/` (the documentation site), `scripts/` (build -and comparison helpers), and `e2e/` (Playwright tests). +`docs/` (every authored documentation page, from the landing page to the +reference docs), `www/` (the documentation site build: its configuration and +gitignored build artifacts), `scripts/` (build and comparison helpers), and +`e2e/` (Playwright tests). + +Contributor-facing deep dives — [creating CLI +commands](docs/contributing/commands.md) and [creating +comparators](docs/contributing/comparators.md) — live under +`docs/contributing/`; the rest of `docs/` is user-facing. ### Running the Tool Locally @@ -106,7 +114,7 @@ and comparison helpers), and `e2e/` (Playwright tests). For fast iteration during development, target a single Markdown file instead of all API docs: ```bash - node packages/core/bin/cli.mjs generate \ + node packages/cli/bin/cli.mjs generate \ -t legacy-html \ -i ../node/doc/api/fs.md \ -o out \ @@ -127,7 +135,7 @@ and comparison helpers), and `e2e/` (Playwright tests). Add `--log-level debug` before the `generate` subcommand to see the full pipeline trace: ```bash - node packages/core/bin/cli.mjs --log-level debug generate -t legacy-html -i ../node/doc/api/fs.md -o out + node packages/cli/bin/cli.mjs --log-level debug generate -t legacy-html -i ../node/doc/api/fs.md -o out ``` > [!TIP] diff --git a/README.md b/README.md index b24f5c68..9e394849 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@

- @nodejs/doc-kit is a tool to generate API documentation of Node.js. See this issue for more information. + doc-kit is a tool to generate API documentation of Node.js. See this issue for more information.

@@ -33,18 +33,12 @@ ## Usage -Local invocation: - -```sh -$ npx doc-kit --help -``` - ```sh -$ node packages/core/bin/cli.mjs --help +$ npx @doc-kit/cli --help ``` ``` -Usage: @nodejs/doc-kit [options] [command] +Usage: doc-kit [options] [command] CLI tool to generate the Node.js API documentation @@ -67,7 +61,7 @@ Running `generate` without the required values exits with an error pointing you to the help output. ``` -Usage: @nodejs/doc-kit generate [options] +Usage: doc-kit generate [options] Generate API docs @@ -78,8 +72,8 @@ Options: (json-simple, legacy-html, legacy-html-all, man-page, legacy-json, legacy-json-all, addon-verify, api-links, orama-db, llms-txt, - sitemap, web) or an import specifier for a custom - generator + sitemap, html) or an import specifier for a + custom generator --ignore Ignore file patterns (glob) -o, --output The output directory -p, --threads Number of threads to use (minimum: 1) @@ -101,7 +95,7 @@ Options: To generate a 1:1 match with the [legacy tooling](https://github.com/nodejs/node/tree/main/tools/doc), use the `legacy-html`, `legacy-json`, `legacy-html-all`, and `legacy-json-all` generators. ```sh -npx doc-kit generate \ +npx @doc-kit/cli generate \ -t legacy-html \ -t legacy-json \ -i "path/to/node/doc/api/*.md" \ @@ -111,10 +105,10 @@ npx doc-kit generate \ ### Redesigned -To generate [our redesigned documentation pages](https://nodejs-api-docs-tooling.vercel.app), use the `html` and `orama-db` (for search) generators. These generators live in the separate [`@nodejs/doc-kit-generator-react`](packages/react) package, which must be installed alongside this one. +To generate [our redesigned documentation pages](https://nodejs-api-docs-tooling.vercel.app), use the `html` and `orama-db` (for search) generators. These generators live in the separate [`@doc-kit/generator-react`](packages/react) package, which must be installed alongside this one. ```sh -npx doc-kit generate \ +npx @doc-kit/cli generate \ -t html \ -t orama-db \ -i "path/to/node/doc/api/*.md" \ diff --git a/docs/cli.md b/docs/cli.md index 5171d8ba..e82748e7 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -4,37 +4,39 @@ The `doc-kit` command-line interface. Every option that maps to configuration can also live in a [configuration file](./configuration.md); when both are present, CLI flags win (rule of specifity). -```sh -npx doc-kit [command] [options] +```bash +npx @doc-kit/cli [command] [options] ``` One option applies to every command: -| Option | Description | -| --------------------- | ------------------------------------------------------ | -| `--log-level ` | `debug`, `info` (default), `warn`, `error`, or `fatal` | +- `--log-level ` {string} `debug`, `info`, `warn`, `error`, or + `fatal`. **Default:** `'info'`. ## `doc-kit generate` -```sh -npx doc-kit generate [options] +```bash +npx @doc-kit/cli generate [options] ``` Runs the generators and writes their output. Requires a `target` and an `input`, from flags or the configuration file. -| Option | Description | -| ----------------------------- | ------------------------------------------------------------- | -| `--config-file ` | Use a specific configuration file instead of searching | -| `-i`, `--input ` | Input file patterns (glob) | -| `-t`, `--target ` | Generator name(s), or import specifiers for custom generators | -| `--ignore ` | Input patterns to skip | -| `-o`, `--output

` | The output directory | -| `-v`, `--version ` | The version of the project being documented | -| `-c`, `--changelog ` | Changelog URL or path (release history for version selectors) | -| `--git-ref ` | Git ref used in source links | -| `--index ` | `index.md` URL or path | -| `--minify` | Minify the output | -| `--type-map ` | Type map URL or path (custom type-name → URL links) | -| `-p`, `--threads ` | Worker threads to use (minimum 1) | -| `--chunk-size ` | Items per worker thread (minimum 1) | +- `--config-file ` {string} Use a specific configuration file instead + of searching. +- `-i, --input ` {string[]} Input file patterns (glob). +- `-t, --target ` {string[]} Generator name(s), or import + specifiers for custom generators. +- `--ignore ` {string[]} Input patterns to skip. +- `-o, --output ` {string} The output directory. +- `-v, --version ` {string} The version of the project being + documented. +- `-c, --changelog ` {string} Changelog URL or path (release history + for version selectors). +- `--git-ref ` {string} Git ref used in source links. +- `--index ` {string} `index.md` URL or path. +- `--minify` {boolean} Minify the output. +- `--type-map ` {string} Type map URL or path (custom type-name → URL + links). +- `-p, --threads ` {number} Worker threads to use (minimum 1). +- `--chunk-size ` {number} Items per worker thread (minimum 1). diff --git a/docs/commands.md b/docs/commands.md deleted file mode 100644 index 21785977..00000000 --- a/docs/commands.md +++ /dev/null @@ -1,185 +0,0 @@ -# Creating Commands - -## Command Structure - -Commands in `doc-kit` are defined as modules that export a command object conforming to the `Command` interface: - -```typescript -interface Command { - name: string; - description: string; - options: { [key: string]: Option }; - action: (options: any) => Promise; -} -``` - -Each command consists of: - -- **name**: The command name used in the CLI (e.g., `generate`) -- **description**: A short description shown in help text -- **options**: An object mapping option names to their definitions -- **action**: The async function that executes when the command is run - -## Creating a New Command - -### Step 1: Create the Command File - -Create a new file in `packages/core/bin/commands/` with your command name: - -```javascript -// packages/core/bin/commands/my-command.mjs -import logger from '../../src/logger/index.mjs'; - -/** - * @type {import('./types').Command} - */ -export default { - name: 'my-command', - description: 'Does something useful', - - options: { - // Define your options here (see next section) - }, - - async action(opts) { - logger.info('Starting my-command', opts); - - // Your command logic here - - logger.info('Completed my-command'); - }, -}; -``` - -### Step 2: Register the Command - -Add your command to the exports in `packages/core/bin/commands/index.mjs`: - -```javascript -import generate from './generate.mjs'; -import myCommand from './my-command.mjs'; // Add this - -export default [ - generate, - myCommand, // Add this -]; -``` - -### Step 3: Update CLI Entry Point - -The CLI in `packages/core/bin/cli.mjs` automatically loads commands from `packages/core/bin/commands/index.mjs`, so no changes are needed there if you followed step 2. - -## Command Options - -Options define the flags and parameters your command accepts. Each option has: - -```typescript -interface Option { - flags: string[]; // CLI flags (e.g., ['-i', '--input ']) - desc: string; // Description for help text -} -``` - -### Defining Options - -```javascript -options: { - input: { - flags: ['-i', '--input '], - desc: 'Input file patterns (glob)', - prompt: { - type: 'text', - message: 'Enter input glob patterns', - variadic: true, - required: true, - }, - }, - - force: { - flags: ['-f', '--force'], - desc: 'Force overwrite existing files', - prompt: { - type: 'confirm', - message: 'Overwrite existing files?', - initialValue: false, - }, - }, - - mode: { - flags: ['-m', '--mode '], - desc: 'Operation mode', - prompt: { - type: 'select', - message: 'Choose operation mode', - options: [ - { label: 'Fast', value: 'fast' }, - { label: 'Thorough', value: 'thorough' }, - ], - }, - }, -} -``` - -### Flag Syntax - -- `` - Required argument -- `[value]` - Optional argument -- `` - Variadic (multiple values) -- `[values...]` - Optional variadic - -### Option Types - -#### `text` - -Single-line text input. - -```javascript -prompt: { - type: 'text', - message: 'Enter a value', - initialValue: 'default', - required: true, -} -``` - -#### `confirm` - -Yes/no confirmation. - -```javascript -prompt: { - type: 'confirm', - message: 'Are you sure?', - initialValue: false, -} -``` - -#### `select` - -Single choice from a list. - -```javascript -prompt: { - type: 'select', - message: 'Choose one', - options: [ - { label: 'Option 1', value: 'opt1' }, - { label: 'Option 2', value: 'opt2' }, - ], -} -``` - -#### `multiselect` - -Multiple choices from a list. - -```javascript -prompt: { - type: 'multiselect', - message: 'Choose multiple', - options: [ - { label: 'Choice A', value: 'a' }, - { label: 'Choice B', value: 'b' }, - ], -} -``` diff --git a/docs/configuration.md b/docs/configuration.md index 983bef22..8aa63a49 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -20,7 +20,7 @@ JavaScript and TypeScript configuration files export the configuration object. JSON and YAML files contain the object directly. A `package.json` configuration uses the `doc-kit` property: -```json +```json displayName="package.json" { "doc-kit": { "target": ["json-simple"], @@ -34,7 +34,7 @@ uses the `doc-kit` property: ### Basic Example -```javascript +```mjs displayName="doc-kit.config.mjs" export default { // Targets, alternatively supplied by command line flags. Each entry is // either a built-in shorthand name or an import specifier resolving to a @@ -72,7 +72,7 @@ are merged underneath its own. Each entry is either an import specifier of a module whose default export is a configuration object, or a path relative to the configuration file: -```mjs +```mjs displayName="doc-kit.config.mjs" export default { // Build the docs the way nodejs.org does — branding, URL layouts, // and release history included @@ -101,39 +101,46 @@ Three sources, in order of precedence: 2. **the configuration file**, which overrides 3. **built-in defaults**. -| Property | Type | Description | Default | -| ------------ | ------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------- | -| `project` | `string` | Name of the project being documented, used in titles, logos, and templated text | The `name` in your `package.json` | -| `version` | `string \| SemVer` | Documentation version | `process.version` | -| `minify` | `boolean` | Whether to minify output | `true` | -| `repository` | `string` | GitHub repository in `owner/repo` format; without one, repository UI is omitted | - | -| `ref` | `string` | Git reference (branch, tag, or commit SHA) | `'HEAD'` | -| `baseURL` | `string \| URL` | Base URL of the published site, used wherever absolute URLs are needed | - | -| `input` | `string[]` | Input directory path | - | -| `output` | `string` | Output directory path | - | -| `ignore` | `string[]` | Patterns to ignore | `[]` | -| `changelog` | `string \| URL \| Array` | Release history used for version selectors; a URL or path to parse, or a pre-parsed array | `[]` (single-version output) | -| `index` | `string \| URL \| Array` | Index URL | - | - ## Global options -Each generator (e.g., `html`, `legacy-json`) can have its own configuration that overrides global settings: +Everything under the `global` key applies to every generator: + +- `project` {string} Name of the project being documented, used in titles, + logos, and templated text. Defaults to the `name` in your `package.json`. +- `version` {string|SemVer} Documentation version. **Default:** + `process.version`. +- `minify` {boolean} Whether to minify output. **Default:** `true`. +- `repository` {string} GitHub repository in `owner/repo` format; without + one, repository UI is omitted. +- `ref` {string} Git reference (branch, tag, or commit SHA). **Default:** + `'HEAD'`. +- `baseURL` {string|URL} Base URL of the published site, used wherever + absolute URLs are needed. +- `input` {string[]} Input file patterns (glob). +- `output` {string} Output directory path. +- `ignore` {string[]} Patterns to ignore. **Default:** `[]`. +- `changelog` {string|URL|Array} Release history used for version selectors; + a URL or path to parse, or a pre-parsed array. **Default:** `[]` + (single-version output). +- `index` {string|URL|Array} Index URL. + +A generator's own section (e.g., `html`, `legacy-json`) can override any of +these for that generator alone. ## Execution options Top-level, alongside `target` and `global`: -| Property | Type | Description | Default | -| ----------- | -------- | ----------------------------------- | -------------- | -| `threads` | `number` | Worker threads used for generation. | Your CPU count | -| `chunkSize` | `number` | Items processed per worker thread. | `10` | +- `threads` {number} Worker threads used for generation. Defaults to your + CPU count. +- `chunkSize` {number} Items processed per worker thread. **Default:** `10`. ## Generator options Each generator documents its own options on its reference page — see the [generators overview](./generators.md). Two commonly configured ones: -```js +```mjs displayName="doc-kit.config.mjs" export default { global: { version: '1.2.0', diff --git a/docs/contributing/commands.md b/docs/contributing/commands.md new file mode 100644 index 00000000..611c5a22 --- /dev/null +++ b/docs/contributing/commands.md @@ -0,0 +1,74 @@ +# Creating Commands + +The `doc-kit` CLI is built on [Commander](https://www.npmjs.com/package/commander). +Each command is a module in `packages/cli/bin/commands/` whose default export +is a Commander `Command` instance; the CLI entry point registers every command +exported from `packages/cli/bin/commands/index.mjs`. + +Today the CLI ships a single command, [`generate`](../cli.md). + +## Creating a New Command + +### Step 1: Create the Command File + +Create a new file in `packages/cli/bin/commands/` with your command name: + +```mjs displayName="packages/cli/bin/commands/my-command.mjs" +import { Command, Option } from 'commander'; + +import { errorWrap } from '../utils.mjs'; + +export default new Command('my-command') + .description('Does something useful') + .addOption(new Option('-f, --force', 'Force overwrite existing files')) + .action( + errorWrap(async opts => { + // Your command logic here + }) + ); +``` + +`errorWrap` catches both synchronous and asynchronous errors, logs them, and +exits with a non-zero status — wrap every action with it so failures are +reported consistently. + +### Step 2: Register the Command + +Add your command to the exports in `packages/cli/bin/commands/index.mjs`: + +```mjs displayName="packages/cli/bin/commands/index.mjs" +import generate from './generate.mjs'; +import myCommand from './my-command.mjs'; // Add this + +export default [ + generate, + myCommand, // Add this +]; +``` + +The CLI in `packages/cli/bin/cli.mjs` registers every command in that array, +so no further changes are needed. + +## Command Options + +Options use Commander's `Option` class directly; see the [Commander +documentation](https://www.npmjs.com/package/commander#options) for the full +API. + +```js +.addOption(new Option('-i, --input ', 'Input file patterns (glob)')) +.addOption(new Option('-o, --output ', 'The output directory')) +.addOption( + new Option('--log-level ', 'Log level').choices(['debug', 'info']) +) +``` + +### Flag Syntax + +- `` - Required argument +- `[value]` - Optional argument +- `` - Variadic (multiple values) +- `[values...]` - Optional variadic + +One global option, `--log-level`, is defined on the program itself in +`packages/cli/bin/cli.mjs` and applies to every command. diff --git a/docs/comparators.md b/docs/contributing/comparators.md similarity index 78% rename from docs/comparators.md rename to docs/contributing/comparators.md index 1cafcd52..2743a7e9 100644 --- a/docs/comparators.md +++ b/docs/contributing/comparators.md @@ -1,6 +1,6 @@ # Creating Comparators -This guide explains how to create build comparison scripts for `@nodejs/doc-kit`. Comparators help identify differences between documentation builds, useful for CI/CD and regression testing. +This guide explains how to create build comparison scripts for `@doc-kit/core`. Comparators help identify differences between documentation builds, useful for CI/CD and regression testing. ## Comparator Concepts @@ -21,14 +21,18 @@ Comparators are scripts that: ## Comparator Structure -Comparators are standalone ESM scripts located in `scripts/comparators/`: - -``` -scripts/comparators/ -├── constants.mjs # Shared constants (BASE, HEAD, TITLE paths) -├── file-size.mjs # Compare file sizes between builds -├── object-assertion.mjs # Deep equality assertion for JSON objects -└── your-comparator.mjs # Your new comparator +Comparators are standalone ESM scripts located in `scripts/comparators/`, +sharing the `BASE`, `HEAD`, and `TITLE` constants from `scripts/constants.mjs`: + +```text +scripts/ +├── constants.mjs # Shared constants (BASE, HEAD, TITLE) +└── comparators/ + ├── file-size.mjs # Compare file sizes and performance between builds + ├── files.mjs # Shared output-file listing helpers + ├── object-assertion.mjs # Deep equality assertion for JSON objects + ├── performance.mjs # Compare benchmark measurements + └── your-comparator.mjs # Your new comparator ``` ### Naming Convention @@ -49,16 +53,18 @@ runs and the performance section is omitted. ### Step 1: Create the Comparator File -Create a new file in `scripts/compare-builds/` with the same name as your generator: +Create a new file in `scripts/comparators/` with the same name as your generator: -```javascript -// scripts/compare-builds/my-format.mjs +```mjs displayName="scripts/comparators/my-format.mjs" import { readdir, readFile } from 'node:fs/promises'; import { join } from 'node:path'; -import { BASE, HEAD, TITLE } from './utils.mjs'; + +import { BASE, HEAD, TITLE } from '../constants.mjs'; // Fetch files from both directories -const [baseFiles, headFiles] = await Promise.all([BASE, HEAD].map(() => await readdir(dir))); +const [baseFiles, headFiles] = await Promise.all( + [BASE, HEAD].map(dir => readdir(dir)) +); // Find all unique files across both builds const allFiles = [...new Set([...baseFiles, ...headFiles])]; @@ -89,8 +95,12 @@ const compareFile = async file => { } catch (error) { // File missing in one of the builds const exists = await Promise.all([ - readFile(basePath, 'utf-8').then(() => true).catch(() => false), - readFile(headPath, 'utf-8').then(() => true).catch(() => false), + readFile(basePath, 'utf-8') + .then(() => true) + .catch(() => false), + readFile(headPath, 'utf-8') + .then(() => true) + .catch(() => false), ]); if (exists[0] && !exists[1]) { @@ -144,7 +154,9 @@ if (differences.length > 0) { modified.forEach(({ file, baseSize, headSize }) => { const diff = headSize - baseSize; const sign = diff > 0 ? '+' : ''; - console.log(`| \`${file}\` | ${baseSize} | ${headSize} | ${sign}${diff} |`); + console.log( + `| \`${file}\` | ${baseSize} | ${headSize} | ${sign}${diff} |` + ); }); console.log(''); } @@ -161,7 +173,7 @@ export BASE=path/to/base/output export HEAD=path/to/head/output # Run the comparator -node scripts/compare-builds/my-format.mjs +node scripts/comparators/my-format.mjs ``` ### Step 3: Integrate with CI/CD diff --git a/docs/creating-generators.md b/docs/creating-generators.md index 360a3cad..6580fbbc 100644 --- a/docs/creating-generators.md +++ b/docs/creating-generators.md @@ -1,6 +1,6 @@ # Creating Generators -This guide explains how to create new documentation generators for `@nodejs/doc-kit`. +This guide explains how to create new documentation generators for `@doc-kit/core`. ## Generator Concepts @@ -12,7 +12,7 @@ Generators in `doc-kit` transform API documentation through a pipeline. Each gen ### Generator Pipeline -``` +```text Raw Markdown Files ↓ [ast] - Parse to MDAST @@ -36,7 +36,7 @@ A generator is defined as a module exporting an object conforming to the `Genera Create a new directory in your project: -``` +```text / ├── index.mjs # Generator metadata (required) ├── generate.mjs # Generator implementation (required) @@ -50,7 +50,7 @@ Create a new directory in your project: Create a `types.d.ts` file containing a `Generator` export. Use this when typing your generator. -```ts +```typescript displayName="types.d.ts" export type Generator = GeneratorMetadata< { // If your generator supports a custom configuration, @@ -72,7 +72,7 @@ export type Generator = GeneratorMetadata< A generator module's default export is a plain object with its metadata and implementation. Create it in `index.mjs`: -```javascript +```mjs displayName="index.mjs" import { generate } from './generate.mjs'; /** @@ -87,7 +87,7 @@ export default { // This generator depends on the metadata generator. Dependencies are // declared as import specifiers, so they can live in any package. - dependsOn: '@nodejs/doc-kit/metadata', + dependsOn: '@doc-kit/core/metadata', defaultConfiguration: { // If your generator supports a custom configuration, define the defaults here @@ -106,7 +106,7 @@ export default { Create the generator implementation in `generate.mjs`: -```javascript +```mjs displayName="generate.mjs" import { writeFile } from 'node:fs/promises'; import { join } from 'node:path'; @@ -156,20 +156,20 @@ to a module whose default export is a generator works as a `--target`: ```bash # A package (subpath) export -doc-kit generate -t @my-scope/my-package/my-format ... +npx @doc-kit/cli generate -t @my-scope/my-package/my-format ... # A local file -doc-kit generate -t ./generators/my-format/index.mjs ... +npx @doc-kit/cli generate -t ./generators/my-format/index.mjs ... ``` Built-in generators additionally get a shorthand alias in `packages/core/src/generators/index.mjs`, which maps the name users type to the import specifier it resolves to: -```javascript +```mjs displayName="packages/core/src/generators/index.mjs" export const publicGenerators = { - 'json-simple': '@nodejs/doc-kit/json-simple', - 'my-format': '@nodejs/doc-kit/my-format', // Add this + 'json-simple': '@doc-kit/core/json-simple', + 'my-format': '@doc-kit/core/my-format', // Add this // ... other generators }; ``` @@ -185,7 +185,7 @@ For generators processing large datasets, implement parallel processing using wo First, define the generator metadata in `index.mjs`: -```javascript +```mjs displayName="index.mjs" import { generate, processChunk } from './generate.mjs'; /** @@ -196,7 +196,7 @@ export default { description: 'Processes data in parallel', - dependsOn: '@nodejs/doc-kit/metadata', + dependsOn: '@doc-kit/core/metadata', // Indicates this generator has a processChunk implementation hasParallelProcessor: true, @@ -208,7 +208,7 @@ export default { Then, implement both `processChunk` and `generate` in `generate.mjs`: -```javascript +```mjs displayName="generate.mjs" import getConfig from '../../utils/configuration/index.mjs'; /** @@ -280,7 +280,7 @@ Generators can yield results as they're produced using async generators. Define the generator metadata in `index.mjs`: -```javascript +```mjs displayName="index.mjs" import { generate, processChunk } from './generate.mjs'; /** @@ -291,7 +291,7 @@ export default { description: 'Streams results as they are ready', - dependsOn: '@nodejs/doc-kit/metadata', + dependsOn: '@doc-kit/core/metadata', hasParallelProcessor: true, @@ -302,7 +302,7 @@ export default { Implement the generator in `generate.mjs`: -```javascript +```mjs displayName="generate.mjs" /** * Process a chunk of data * @@ -339,7 +339,7 @@ Some generators must collect all input before processing. Generator metadata in `index.mjs`: -```javascript +```mjs displayName="index.mjs" import { generate } from './generate.mjs'; /** @@ -350,7 +350,7 @@ export default { description: 'Requires all input at once', - dependsOn: '@nodejs/doc-kit-generator-react/jsx-ast', + dependsOn: '@doc-kit/generator-react/jsx-ast', generate, }; @@ -358,7 +358,7 @@ export default { Implementation in `generate.mjs`: -```javascript +```mjs displayName="generate.mjs" /** * Non-streaming - returns Promise instead of AsyncGenerator * @@ -387,7 +387,7 @@ Use non-streaming when: In `index.mjs`: -```javascript +```mjs displayName="index.mjs" import { generate } from './generate.mjs'; export default { @@ -395,7 +395,7 @@ export default { // This generator requires the metadata generator's output. The dependency // is an import specifier, so it may point at any installed package. - dependsOn: '@nodejs/doc-kit/metadata', + dependsOn: '@doc-kit/core/metadata', // ... other metadata @@ -405,7 +405,7 @@ export default { In `generate.mjs`: -```javascript +```mjs displayName="generate.mjs" export async function generate(input, worker) { // input contains the output from 'metadata' generator } @@ -417,7 +417,7 @@ export async function generate(input, worker) { In `generate.mjs`: -```javascript +```mjs displayName="generate.mjs" import { mkdir, writeFile } from 'node:fs/promises'; import { join } from 'node:path'; @@ -452,7 +452,7 @@ export async function generate(input, worker) { ### Copying Assets -```javascript +```mjs displayName="generate.mjs" import { cp } from 'node:fs/promises'; import { join } from 'node:path'; diff --git a/docs/customization.md b/docs/customization.md index 92d69b56..19dbc901 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -6,8 +6,7 @@ order they usually make them. The complete option list lives in the All of it goes in the `html` section of your configuration file: -```js -// doc-kit.config.mjs +```mjs displayName="doc-kit.config.mjs" export default { target: ['html'], global: { @@ -140,7 +139,7 @@ html: { }, ``` -```md +```md displayName="welcome.mdx" --- title: Welcome --- @@ -159,8 +158,8 @@ signature parsing while keeping headings, TOC, and sidebar behavior. Vite builds the site by default, and accepts your plugins and options: -```js -import { createViteBundler } from '@nodejs/doc-kit-generator-react/html/bundlers/vite'; +```mjs displayName="doc-kit.config.mjs" +import { createViteBundler } from '@doc-kit/generator-react/html/bundlers/vite'; export default { html: { diff --git a/docs/generators.md b/docs/generators.md index 10d19690..dd553666 100644 --- a/docs/generators.md +++ b/docs/generators.md @@ -3,12 +3,12 @@ A generator is an output format. ```bash -npx doc-kit generate -t html -t orama-db -t sitemap -i "docs/**/*.md" -o out +npx @doc-kit/cli generate -t html -t orama-db -t sitemap -i "docs/**/*.md" -o out ``` ## Built-in generators -### Web ([`@nodejs/doc-kit-generator-react`](./packages/react.md)) +### Web ([`@doc-kit/generator-react`](./packages/react.md)) | Target | Output | | -------------------------------------- | -------------------------------------------------------------------- | @@ -17,13 +17,13 @@ npx doc-kit generate -t html -t orama-db -t sitemap -i "docs/**/*.md" -o out | [`llms-txt`](./generators/llms-txt.md) | An [`llms.txt`](https://llmstxt.org/) index for language models. | | [`sitemap`](./generators/sitemap.md) | A `sitemap.xml` for search engines. | -### JSON ([`@nodejs/doc-kit`](./packages/core.md)) +### JSON ([`@doc-kit/core`](./packages/core.md)) | Target | Output | | -------------------------------------------- | -------------------------------------------------------- | | [`json-simple`](./generators/json-simple.md) | A simplified JSON rendering of the parsed documentation. | -### Legacy ([`@nodejs/doc-kit-generator-legacy`](./packages/legacy.md)) +### Legacy ([`@node-core/doc-kit-legacy`](./packages/node-legacy.md)) 1:1 matches for Node.js's original documentation tooling, for consumers of the classic layouts. @@ -63,7 +63,7 @@ A target can also be an import specifier — a package export or a local file whose default export is a generator: ```bash -npx doc-kit generate -t @my-scope/my-generator -t ./generators/rss.mjs ... +npx @doc-kit/cli generate -t @my-scope/my-generator -t ./generators/rss.mjs ... ``` To build one, see [Creating generators](./creating-generators.md). diff --git a/www/pages/getting-started.md b/docs/getting-started.md similarity index 78% rename from www/pages/getting-started.md rename to docs/getting-started.md index 02996e4b..a4c8f575 100644 --- a/www/pages/getting-started.md +++ b/docs/getting-started.md @@ -3,13 +3,13 @@ First, install doc-kit and a generator, like so: ```bash -npm install --save-dev @nodejs/doc-kit @nodejs/doc-kit-generator-react +npm install --save-dev @doc-kit/cli @doc-kit/generator-react ``` Then, create your configuration file set up for your project: -```js displayName="doc-kit.config.mjs" -/** @type {import('@nodejs/doc-kit/utils/configuration/types').Configuration} */ +```mjs displayName="doc-kit.config.mjs" +/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */ export default { target: ['html'], @@ -21,7 +21,7 @@ export default { ``` `doc-kit generate` reads that configuration; every option can also be passed as -a CLI flag. See the [configuration reference](./configuration.html) for +a CLI flag. See the [configuration reference](./configuration.md) for everything the file accepts. ## Build and preview it @@ -29,7 +29,7 @@ everything the file accepts. With at least one Markdown file under `docs/`, build the site: ```bash -npx doc-kit generate +npx @doc-kit/cli generate ``` The pages land in `out/`. They use import maps and client-side hydration, so @@ -37,7 +37,7 @@ serve them over HTTP rather than opening the files from disk; any static server works: ```bash -npx doc-kit generate -t html -t orama-db -i "docs/*.md" -o out +npx @doc-kit/cli generate -t html -t orama-db -i "docs/*.md" -o out ``` ## Preview it locally @@ -61,10 +61,10 @@ through a couple quick changes. Create a `doc-kit.config.mjs` file at the root of the project. -```mjs +```mjs displayName="doc-kit.config.mjs" import { join } from 'node:path'; -/** @type {import('@nodejs/doc-kit/src/utils/configuration/types').Configuration} */ +/** @type {import('@doc-kit/core/src/utils/configuration/types').Configuration} */ export default { global: { project: 'My Project', // Project name used in titles, the logo, and templates @@ -106,9 +106,9 @@ on screen. ## Next steps -- [Writing documentation](./writing-docs.html) — the Markdown conventions that +- [Writing documentation](./writing-docs.md) — the Markdown conventions that make `doc-kit` more than a static-site generator. -- [Customizing the site](./customization.html) — your name, logo, navigation, +- [Customizing the site](./customization.md) — your name, logo, navigation, and components instead of the defaults. -- [Publishing your docs](./publishing.html) — production builds, base URLs, and +- [Publishing your docs](./publishing.md) — production builds, base URLs, and hosting. diff --git a/www/pages/index.md b/docs/index.md similarity index 57% rename from www/pages/index.md rename to docs/index.md index 33a3a83b..05229c9c 100644 --- a/www/pages/index.md +++ b/docs/index.md @@ -1,11 +1,8 @@ # `doc-kit` -`doc-kit` turns API-shaped Markdown into documentation. - -> 📣 `doc-kit` is in beta. We'd love feedback in the -> [issue tracker](https://github.com/nodejs/doc-kit/issues) or the -> [#nodejs-website channel](https://openjs-foundation.slack.com/archives/CVAMEJ4UV) -> on [the OpenJS Slack](http://slack.openjsf.org/). +`doc-kit` turns API-shaped Markdown into documentation. We'd love +feedback in the [issue tracker][] or the [#nodejs-website channel][] +on [the OpenJS Slack][]. ## Showcase @@ -17,3 +14,7 @@ A few places `doc-kit` is already in use. Feel free to PR yours. - - `html`, `orama-db`, `llms-txt` - - `html`, `orama-db`, `llms-txt` - - `html`, `orama-db`, `llms-txt` + +[issue tracker]: https://github.com/nodejs/doc-kit/issues +[#nodejs-website channel]: https://openjs-foundation.slack.com/archives/CVAMEJ4UV +[the OpenJS Slack]: http://slack.openjsf.org/ diff --git a/docs/publishing.md b/docs/publishing.md index 43a726e1..94b47580 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -4,7 +4,7 @@ is as simple as hosting the output directory. ```bash -npx doc-kit generate +npx @doc-kit/cli generate ``` Everything lands in your configured `output` directory (`out/` by @@ -29,7 +29,7 @@ Set `baseURL` to where the site will live. Generators that emit absolute URLs (e.g., `sitemap`, `llms-txt`) will need it in order to generate their output. -```js displayName="doc-kit.config.mjs" +```mjs displayName="doc-kit.config.mjs" export default { global: { baseURL: 'https://example.com/docs', @@ -47,7 +47,7 @@ export default { Search engines and language models each get their own artifact — add the generators and they share the same parse: -```js +```mjs displayName="doc-kit.config.mjs" target: ['html', 'orama-db', 'sitemap', 'llms-txt'], ``` diff --git a/docs/specification.md b/docs/specification.md index a1f75ad5..0b5b11c9 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -5,7 +5,7 @@ **Authored By**: Aviv Keller () This document specifies the Markdown format consumed by -[`@nodejs/doc-kit`][doc-kit]. It defines the structural, syntactic, and +[`@doc-kit/core`][doc-kit]. It defines the structural, syntactic, and semantic rules that documents MUST follow to be correctly parsed. The format is a strict superset of [GitHub Flavored Markdown][gfm] (which itself is a strict superset of [CommonMark][commonmark]), adding conventions for API diff --git a/eslint.config.mjs b/eslint.config.mjs index 5f890af3..9375e8cb 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -95,7 +95,7 @@ export default defineConfig([ }, { files: [ - 'packages/legacy/src/legacy-html/assets/*.js', + 'packages/node-legacy/src/legacy-html/assets/*.js', 'packages/react/src/html/ui/**/*', ], languageOptions: { diff --git a/package-lock.json b/package-lock.json index b88fa56f..c532cad4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { - "name": "@nodejs/doc-kit-monorepo", + "name": "@doc-kit/core-monorepo", "version": "1.4.3", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "@nodejs/doc-kit-monorepo", + "name": "@doc-kit/core-monorepo", "workspaces": [ "packages/*" ], @@ -415,6 +415,18 @@ "url": "https://github.com/prettier/prettier?sponsor=1" } }, + "node_modules/@doc-kit/cli": { + "resolved": "packages/cli", + "link": true + }, + "node_modules/@doc-kit/core": { + "resolved": "packages/core", + "link": true + }, + "node_modules/@doc-kit/generator-react": { + "resolved": "packages/react", + "link": true + }, "node_modules/@emnapi/core": { "version": "1.11.1", "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.1.tgz", @@ -1331,6 +1343,10 @@ "resolved": "packages/node", "link": true }, + "node_modules/@node-core/doc-kit-legacy": { + "resolved": "packages/node-legacy", + "link": true + }, "node_modules/@node-core/rehype-shiki": { "version": "1.4.3", "resolved": "https://registry.npmjs.org/@node-core/rehype-shiki/-/rehype-shiki-1.4.3.tgz", @@ -1387,18 +1403,6 @@ "node": ">=20" } }, - "node_modules/@nodejs/doc-kit": { - "resolved": "packages/core", - "link": true - }, - "node_modules/@nodejs/doc-kit-generator-legacy": { - "resolved": "packages/legacy", - "link": true - }, - "node_modules/@nodejs/doc-kit-generator-react": { - "resolved": "packages/react", - "link": true - }, "node_modules/@nodelib/fs.scandir": { "version": "2.1.5", "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", @@ -11213,8 +11217,19 @@ "url": "https://github.com/sponsors/wooorm" } }, + "packages/cli": { + "name": "@doc-kit/cli", + "version": "0.0.0", + "dependencies": { + "@doc-kit/core": "^0.0.0", + "commander": "^15.0.0" + }, + "bin": { + "doc-kit": "bin/cli.mjs" + } + }, "packages/core": { - "name": "@nodejs/doc-kit", + "name": "@doc-kit/core", "version": "0.0.0", "dependencies": { "@actions/core": "^3.0.0", @@ -11222,7 +11237,6 @@ "@swc/html-wasm": "^1.15.46", "@swc/wasm": "^1.15.46", "acorn": "^8.17.0", - "commander": "^15.0.0", "cosmiconfig": "^9.0.2", "dedent": "^1.7.2", "github-slugger": "^2.0.0", @@ -11247,57 +11261,54 @@ "unist-util-visit": "^5.1.0", "yaml": "^2.9.0" }, - "bin": { - "doc-kit": "bin/cli.mjs" - }, "peerDependencies": { + "@doc-kit/generator-react": "^0.0.0", "@node-core/doc-kit": "^1.4.3", - "@nodejs/doc-kit-generator-legacy": "^0.0.0", - "@nodejs/doc-kit-generator-react": "^0.0.0" + "@node-core/doc-kit-legacy": "^0.0.0" }, "peerDependenciesMeta": { - "@node-core/doc-kit": { + "@doc-kit/generator-react": { "optional": true }, - "@nodejs/doc-kit-generator-legacy": { + "@node-core/doc-kit": { "optional": true }, - "@nodejs/doc-kit-generator-react": { + "@node-core/doc-kit-legacy": { "optional": true } } }, - "packages/legacy": { - "name": "@nodejs/doc-kit-generator-legacy", - "version": "0.0.0", - "dependencies": { - "@nodejs/doc-kit": "^0.0.0", - "hastscript": "^9.0.1", - "unist-builder": "^4.0.0", - "unist-util-visit": "^5.1.0" - } - }, "packages/node": { "name": "@node-core/doc-kit", "version": "1.4.3", "dependencies": { - "@nodejs/doc-kit": "^0.0.0", + "@doc-kit/core": "^0.0.0", "dedent": "^1.7.2", "estree-util-visit": "^2.0.0", "unist-util-visit": "^5.1.0" } }, + "packages/node-legacy": { + "name": "@node-core/doc-kit-legacy", + "version": "0.0.0", + "dependencies": { + "@doc-kit/core": "^0.0.0", + "hastscript": "^9.0.1", + "unist-builder": "^4.0.0", + "unist-util-visit": "^5.1.0" + } + }, "packages/react": { - "name": "@nodejs/doc-kit-generator-react", + "name": "@doc-kit/generator-react", "version": "0.0.0", "dependencies": { "@11ty/is-land": "^5.0.1", + "@doc-kit/core": "^0.0.0", "@fontsource-variable/open-sans": "^5.3.0", "@fontsource/ibm-plex-mono": "^5.3.0", "@heroicons/react": "^2.2.0", "@node-core/rehype-shiki": "^1.4.3", "@node-core/ui-components": "^1.7.4", - "@nodejs/doc-kit": "^0.0.0", "@orama/orama": "^3.1.18", "@orama/ui": "^1.5.4", "estree-util-to-js": "^2.0.0", diff --git a/package.json b/package.json index 5bb1e54f..85fcca92 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "@nodejs/doc-kit-monorepo", + "name": "@doc-kit/core-monorepo", "private": true, "type": "module", "workspaces": [ @@ -21,8 +21,8 @@ "test:watch": "node --test --experimental-test-module-mocks --watch \"packages/*/src/**/*.test.mjs\" \"scripts/**/*.test.mjs\"", "test:e2e": "playwright test", "prepare": "husky || exit 0", - "run": "node packages/core/bin/cli.mjs", - "watch": "node --watch packages/core/bin/cli.mjs", + "run": "node packages/cli/bin/cli.mjs", + "watch": "node --watch packages/cli/bin/cli.mjs", "docs:build": "bash scripts/vercel-docs-build.sh", "changeset": "changeset", "changeset:version": "changeset version", diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 00000000..7c570b3b --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,45 @@ +# `@doc-kit/cli` + +The command-line interface for [doc-kit](https://github.com/nodejs/doc-kit): +the `doc-kit` binary that runs the +[`@doc-kit/core`](https://www.npmjs.com/package/@doc-kit/core) engine to turn +API-shaped Markdown into documentation sites, JSON, man pages, and more. + +## Usage + +```sh +npx @doc-kit/cli --help +npx @doc-kit/cli generate --help +``` + +You must provide an input and at least one target through command-line +options or a configuration file. Configuration is discovered automatically +using `cosmiconfig`, or you can select a file explicitly with +`--config-file`. + +```sh +npx @doc-kit/cli generate \ + -t html \ + -i "path/to/docs/**/*.md" \ + -o out +``` + +Built-in generator names resolve to the [`@doc-kit/core` +generators](https://www.npmjs.com/package/@doc-kit/core) and its companion +generator packages, which must be installed alongside this one. Custom +generators load by import specifier — any module whose default export is a +generator works as a `--target`. + +## Contributing + +This package lives in the [nodejs/doc-kit](https://github.com/nodejs/doc-kit) +monorepo. From this directory (or the repository root with +`npm run