docs: publish API docs for every package with doc-kit

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths: &paths
+      - 'docs/**'
+      - 'doc-kit.config.mjs'
+      - 'package.json'
+      # the site shows core's version, which every release bumps
+      - 'core/package.json'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches:
+      - main
+    paths: *paths
+  workflow_dispatch:
+
+permissions: {}
+
+# never cancel a deploy halfway; a PR's newer push replaces its older build
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    if: github.repository == 'cutenode/nodevu'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: lts/*
+      - name: Run npm install
+        run: npm install --workspaces=false
+      - name: Build the docs
+        run: npm run docs
+      - name: Upload the site
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: out
+
+  deploy:
+    needs: build
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write # publish the site
+      id-token: write # prove the deployment comes from this workflow
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

README.md

@@ -1,6 +1,6 @@
 # nodevu
 
-nodevu is a Node.js Version Utility meant to collect, merge, and reason about Node.js versions in a way that's explicitly developer friendly.
+nodevu is a Node.js Version Utility meant to collect, merge, and reason about Node.js versions in a way that's explicitly developer friendly. Its docs live at [cutenode.github.io/nodevu](https://cutenode.github.io/nodevu/).
 
 nodevu is composed of a set of modules:
 
@@ -17,3 +17,11 @@ nodevu is composed of a set of modules:
   - [parsefiles](./parsefiles/): this is a utility for parsing the `files` property of the [Node.js distributions JSON](https://nodejs.org/dist/index.json) file to understand the available files for any given set of identifiers from that list. It also provides additional, potentially useful information.
   - [opt](./opt/): this is a utility for generating a usable `options` for `@nodevu/core`.
   - [fetchindex](./fetchindex/): this is a utility for fetching `/dist/index.json` from `nodejs.org` for `@nodevu/core`. Might be useful for other projects.
+
+## Development
+
+- `npm test` and `npm run coverage` run every module's tests.
+- `npm run lint` checks the whole repo with oxlint and oxfmt.
+- `npm run docs:dev` builds the docs from `docs/pages/` with [doc-kit](https://doc-kit.nodejs.org/) and serves them locally. `npm run docs` only builds them, into `out/`.
+
+Merging to `main` publishes the docs to GitHub Pages.

aliases/README.md

@@ -1,25 +1,9 @@
 # @nodevu/aliases
 
-This is a module that provides an array of aliases for ranges of Node.js release lines.
+The names of the ranges of Node.js release lines that `@nodevu/ranges` works out.
 
-## Usage
-
-```js
-const aliases = require('@nodevu/aliases');
-
-for (const alias of aliases) {
-	console.log(alias);
-}
+```bash
+npm install @nodevu/aliases
 ```
 
-## API
-
-This module returns an `Array` of aliases:
-
-- 'alpha' - This represents the release line in its Alpha phase, if any. Starting with Node.js 27, each release line gets Alpha releases (`vN.0.0-alpha.X.Y.Z`) before its first Current release.
-- 'current' - This represents the current Node.js release line.
-- 'lts/latest' - This represents the latest LTS release line.
-- 'lts/active' - This represents the active LTS release lines.
-- 'lts/maintenance' - This represents the maintenance LTS release line, if any.
-- 'eol' - This represents the End of Life release lines.
-- 'all' - This represents all release lines.
+Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/aliases).

core/README.md

@@ -1,103 +1,9 @@
 # @nodevu/core
 
-The core, online-only utility of nodevu.
+The core, online-only module of nodevu. It fetches the version information Node.js publishes and merges it into one object keyed by release line, with each line's phase, its newest and oldest LTS and security releases, and the files each release ships.
 
-## Usage
-
-```js
-const nodevu = require('@nodevu/core');
-
-async function getData() {
-	const data = await nodevu(); // returns a lot of data!
-	console.log(data);
-}
-
-getData();
+```bash
+npm install @nodevu/core
 ```
 
-## API
-
-assuming you're requiring this module as `nodevu`:
-
-- `nodevu(options)` - returns a promise that resolves to a giant JSON blob of data. This is the default export.
-  - `options` (`Object`, optional): an `Object` of options to pass to the module.
-    - `fetch` (`Object`, optional): your chosen fetch implementation. Default: [Undici](https://github.com/nodejs/undici)'s fetch impelmentation.
-    - `now` (`String`, optional): a custom date `String` (ISO 8601) to do relative checks against. _Most likely_ only useful for internal testing. Default: `DateTime.now()` from [Luxon](https://moment.github.io/luxon/).
-    - `urls` (`Object`, optional): an `Object` that enables you to set custom values for the Node.js `index.json` file and `schedule.json` file.
-      - `index` (`String`, optional): a `String` that, if set, changes the URL that this module looks for the version index file at. This should be a _full_ URL that points to a JSON file. Default: `https://nodejs.org/dist/index.json`.
-      - `schedule` (`String`, optional): a `String` that, if set, changes the URL that this module looks for the Node.js release schedule file at. This should be a _full_ URL that points to a JSON file. Default: `https://raw.githubusercontent.com/nodejs/Release/master/schedule.json` .
-
-The data returned by this module follows a pretty specific structure. Here's a detailing of that structure:
-
-- Everything is within a top level `Object`.
-  - Every key in the`Object`is a semver major release line name with a 'v' prefix. Example: `v17`. Every value is an`Object`with the following properties:
-    - `releases` (`Object`) - an`Object`that is filled with all releases under the release line:
-      - Every key in the`Object`is a full Node.js release name. Example: `v17.6.0`. Every value is an`Object`with the following properties:
-        - `semver` (`Object`) - a small`Object`that gives semver information:
-          - `raw` (`String`) - the whole, raw version.
-          - `major` (`String`) - the semver major number.
-          - `minor` (`String`) - the semver minor number.
-          - `patch` (`String`) - the semver patch number.
-          - `line` (`String`) - the "name" of the release line.
-        - `releaseDate` (`String`) - the version's release date.
-        - `modules` (`Object`)
-          - `version` (`String`) - the ABI (Application Binary Interface) version number of Node.js, used to determine which version of Node.js compiled C++ add-on binaries can be loaded in to without needing to be re-compiled.
-        - `dependencies` (`Object`) - the bundled dependencies in this version of Node.js:
-          - `npm` (`String`) - version of the bundled npm.
-          - `v8` (`String`) - version of the bundled v8.
-          - `uv` (`String`) - version of the bundled libuv.
-          - `zlib` (`String`) - version of the bundled zlib.
-          - `openssl` (`String`) - version of the bundled openssl.
-        - `files` (`Object`) - an`Object`that provides context on the files available for the given release:
-          - `available` (`Array`) - the available files, as listed by the official [dist file](https://nodejs.org/dist/index.json). Every entry will be a String.
-          - `links` (`Object`) - an`Object`of the different potential links:
-            - `aix` (`Array`) - all AIX links (AIX is an IBM platform) links:
-              - `id` (`String`) - the initial identifier from `available` that was passed in.
-              - `files` (`Array`) - an `Array` of associated filenames for the ID.
-              - `architecture` (`String`) - the name of the architecture for the files in `files`.
-            - `headers` (`Array`) - all links to headers for the build:
-              - `id` (`String`) - the initial identifier from `available` that was passed in.
-              - `files` (`Array`) - an `Array` of associated filenames for the ID.
-              - `architecture` (`String`) - the name of the architecture for the files in `files`.
-            - `linux` (`Array`) - all the links to Linux distributions for the build:
-              - `id` (`String`) - the initial identifier from `available` that was passed in.
-              - `files` (`Array`) - an `Array` of associated filenames for the ID.
-              - `architecture` (`String`) - the name of the architecture for the files in `files`.
-            - `macos` (`Array`):
-              - `id` (`String`) - the initial identifier from `available` that was passed in.
-              - `files` (`Array`) - an `Array` of associated filenames for the ID.
-              - `architecture` (`String`) - the name of the architecture for the files in `files`.
-            - `source` (`Array`):
-              - `id` (`String`) - the initial identifier from `available` that was passed in.
-              - `files` (`Array`) - an `Array` of associated filenames for the ID.
-              - `architecture` (`String`) - the name of the architecture for the files in `files`.
-            - `windows` (`Array`):
-              - `id` (`String`) - the initial identifier from `available` that was passed in.
-              - `files` (`Array`) - An `Array` of associated filenames for the ID.
-              - `architecture` (`String`) - The name of the architecture for the files in `files`.
-        - `lts` (`Object`):
-          - `isLts`(Boolean) - `true` if the release is an LTS release, `false` if it's not.
-        - `alpha` (`Object`):
-          - `isAlpha` (Boolean) - `true` if the release is an Alpha release (like `v27.0.0-alpha.0.0.0`), `false` if it's not.
-        - `security` (`Object`):
-          - `isSecurity` (Boolean) - `true` if the release is a security release, `false` if it's not.
-    - `support` (`Object`) - An`Object`to provide information about the project's support of the given release line, including dates, status, LTS codename, and LTS version info:
-      - `codename` (`String`) - **Only present if applicable to the given release.** A `String` of the LTS release line's codename.
-      - `lts` (`Object`) - **Only present if the release line has an LTS date in schedule.json or a release flagged as LTS in index.json.** An`Object`that provides LTS versioning information.
-        - `newest` (`String`) - The newest release in the release line that is LTS. _Usually_, this will be the latest release in the line.
-        - `oldest` (`String`) - **Only present if applicable to the given release.** The oldest (first) release in the release line that was flagged as LTS.
-      - `phases` (`Object`) - Information about each phase of a release line's lifecycle:
-        - `dates` (`Object`) - Start dates for each phase of a release line's lifecycle:
-          - `alpha` (`String`) - **Only present if the release line has an Alpha phase.** The start date of the Alpha phase, before the first Current release of the release line (releases in this phase are `alpha`). Example: `2026-10-28`.
-          - `start` (`String`) - The start date of the release line's Current phase (releases in this phase are `current`). Example: `2021-04-20`.
-          - `lts` (`String`) - **Only present if the release line is an LTS release.** The start date of the LTS lifecycle (releases in this phase are `lts`). Example: `2021-10-26`.
-          - `maintenance` (`String`) - **Only present if the release line has a maintenance phase.** The start date of the maintenance phase of the lifecycle. Example: `2022-10-18`.
-          - `end` (`String`) - the date the release line is no longer supported. Example: `2024-04-30`.
-        - `current` (`String`) - The phase the release line is in, based on `now`: `alpha`, `start`, `lts`, `maintenance`, or `end`. An empty `Object` if no phase has started yet.
-    - `security` (`Object`):
-      - `all` (`Array`) - an `Array` of _all_ security releases in the release line.
-      - `newest` (`String`) - the newest (most recent) security release. Example: `17.3.1`.
-
-### Example output
-
-You can find an example of the output [here](https://gist.github.com/bnb/df2cd4329e9f402bbf8dc9bf8364aa34). It's big. Like, really big. GitHub will struggle to render it. It's probably worth viewing [raw](https://gist.githubusercontent.com/bnb/df2cd4329e9f402bbf8dc9bf8364aa34/raw/2602ad0738bb9b8d0f41c3ad110e8f8a58f12197/data.json) or curl'ing the raw output.
+Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/core).

doc-kit.config.mjs

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// every package is released together, so core's version is the docs' version
+const { version } = JSON.parse(
+	readFileSync(join(import.meta.dirname, 'core', 'package.json'), 'utf8'),
+);
+
+const repository = 'cutenode/nodevu';
+
+const description =
+	'nodevu collects, merges, and reasons about Node.js versions: release lines, LTS and security releases, support phases, and downloadable files.';
+
+/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */
+export default {
+	target: ['html', 'orama-db', 'json', 'llms-txt', 'sitemap'],
+
+	global: {
+		project: 'nodevu',
+		version,
+		repository,
+		ref: 'main',
+		baseURL: 'https://cutenode.github.io/nodevu',
+		input: ['docs/pages/**/*.md'],
+		output: 'out',
+	},
+
+	html: {
+		title: '{project} documentation',
+
+		// all.html and 404.html load their assets from `/` unless URLs are
+		// absolute, which breaks under GitHub Pages' /nodevu/. CI builds what
+		// gets published; local builds stay relative so any static server works
+		useAbsoluteURLs: process.env.CI === 'true',
+		editURL: `https://github.com/${repository}/edit/main/docs/pages{path}.md`,
+
+		// the default copies `static/` into the site, which here is the
+		// @nodevu/static workspace. copy the pages' Markdown instead, since
+		// llms.txt links to it
+		pathsToCopy: [{ [join(import.meta.dirname, 'docs', 'pages')]: '.' }],
+
+		imports: {
+			'#theme/Navigation': join(
+				import.meta.dirname,
+				'docs',
+				'theme',
+				'Navigation.jsx',
+			),
+		},
+
+		navigation: {
+			sidebar: [
+				{
+					groupName: 'Start',
+					items: [{ label: 'nodevu', link: '/index' }],
+				},
+				{
+					groupName: 'Foundational modules',
+					items: [
+						{ label: '`@nodevu/core`', link: '/core' },
+						{ label: '`@nodevu/static`', link: '/static' },
+					],
+				},
+				{
+					groupName: 'Utilities',
+					items: [
+						{ label: '`@nodevu/oldest`', link: '/oldest' },
+						{ label: '`@nodevu/newest`', link: '/newest' },
+						{ label: '`@nodevu/ranges`', link: '/ranges' },
+						{ label: '`@nodevu/aliases`', link: '/aliases' },
+						{ label: '`@nodevu/translate`', link: '/translate' },
+					],
+				},
+				{
+					groupName: 'Helpers',
+					items: [
+						{ label: '`@nodevu/parsefiles`', link: '/parsefiles' },
+						{ label: '`@nodevu/opt`', link: '/opt' },
+						{ label: '`@nodevu/fetchindex`', link: '/fetchindex' },
+					],
+				},
+			],
+		},
+
+		head: {
+			meta: [
+				{ name: 'description', content: description },
+				{ property: 'og:description', content: description },
+			],
+		},
+	},
+};

docs/pages/aliases.md

@@ -0,0 +1,36 @@
+# `@nodevu/aliases`
+
+<!--source_link=aliases/index.js-->
+
+The names of the ranges of Node.js release lines that
+[`@nodevu/ranges`](ranges.md) works out.
+
+```bash
+npm install @nodevu/aliases
+```
+
+The module exports an array of them:
+
+```js
+const aliases = require('@nodevu/aliases');
+
+aliases.includes('lts/active'); // true
+```
+
+## `aliases`
+
+- Type: {string[]}
+
+Every alias, in this order:
+
+- `'alpha'`: the release line in its Alpha phase, if any. Starting with
+  Node.js 27, each line gets Alpha releases (`vN.0.0-alpha.X.Y.Z`) before
+  its first Current release.
+- `'current'`: the Current release line.
+- `'lts/latest'`: the LTS release line in its LTS phase, before
+  maintenance.
+- `'lts/active'`: the LTS release lines in their LTS or maintenance phase,
+  so `'lts/latest'` and `'lts/maintenance'` together.
+- `'lts/maintenance'`: the LTS release lines in their maintenance phase.
+- `'eol'`: the release lines past their end of life.
+- `'all'`: every release line.