docs: add typedoc site

Author: boneskull

.config/typedoc-plugin-bargs.js

@@ -0,0 +1,67 @@
+/**
+ * This mini-plugin copies media files from `site/media/` to the output
+ * directory's `media/` folder at end of rendering.
+ *
+ * @packageDocumentation
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PageEvent, RendererEvent } from 'typedoc';
+
+/**
+ * @import {Application} from "typedoc"
+ */
+
+const SOURCE_DIR = fileURLToPath(new URL('../site/media/', import.meta.url));
+
+/**
+ * @function
+ * @param {Application} app
+ */
+export const load = (app) => {
+  const outputDir = app.options.getValue('out');
+  const mediaDir = path.join(outputDir, 'media');
+
+  // Listen for declaration creation to inspect JSDoc block tags
+
+  app.logger.info(
+    `Will copy all files in ${path.relative(process.cwd(), SOURCE_DIR)} to ${path.relative(process.cwd(), mediaDir)}`,
+  );
+
+  app.renderer.on(RendererEvent.END, () => {
+    for (const file of fs.readdirSync(SOURCE_DIR)) {
+      const sourceFile = path.join(SOURCE_DIR, file);
+      const destFile = path.join(mediaDir, file);
+      fs.cpSync(sourceFile, destFile);
+      app.logger.info(
+        `Copied ${path.relative(process.cwd(), sourceFile)} to ${path.relative(process.cwd(), destFile)}`,
+      );
+    }
+  });
+
+  app.renderer.on(PageEvent.END, (page) => {
+    if (!page.contents) {
+      return;
+    }
+    const navigationLinks = app.options.getValue('navigationLinks');
+    if (!navigationLinks) {
+      return;
+    }
+
+    if ('GitHub' in navigationLinks) {
+      // Replace the GitHub link in the footer with one that includes the icon
+      page.contents = page.contents.replace(
+        `<a href="${navigationLinks.GitHub}">GitHub</a>`,
+        `<a href="${navigationLinks.GitHub}" title="bargs on GitHub"><span class="icon-github" aria-label="GitHub"></span></a>`,
+      );
+    }
+    if ('npm' in navigationLinks) {
+      // Replace the npm link in the footer with one that includes the icon
+      page.contents = page.contents.replace(
+        `<a href="${navigationLinks.npm}">npm</a>`,
+        `<a href="${navigationLinks.npm}" title="@boneskull/bargs on npm"><span class="icon-npm" aria-label="npm"></span></a>`,
+      );
+    }
+  });
+};

.config/typedoc.js

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs';
+
+/**
+ * @import {TypeDocOptions} from "typedoc"
+ */
+
+const customFooterHtml = readFileSync(
+  new URL('../site/media/footer.html', import.meta.url),
+  'utf8',
+);
+
+/** @type {Partial<TypeDocOptions>} */
+export default {
+  basePath: process.env.GITHUB_ACTIONS ? '/bargs/' : '/',
+  customCss: '../site/media/bargs-theme.css',
+  customFooterHtml,
+  darkHighlightTheme: 'vitesse-dark',
+  entryPoints: ['../src/index.ts'],
+  excludeExternals: true,
+  excludeInternal: true,
+  excludePrivate: true,
+  externalSymbolLinkMappings: {
+    '@types/node': {
+      'util.parseArgs': 'https://nodejs.org/api/util.html#utilparseargsconfig',
+    },
+    typescript: {
+      PromiseLike:
+        'https://github.com/microsoft/TypeScript/blob/3320dfdfcf17cdcdbfccb8040ea73cf110d94ba3/src/lib/es5.d.ts', // current of Sep 9 2025
+    },
+  },
+  favicon: '../site/media/favicon.svg',
+  // @ts-expect-error from extras plugin
+  footerLastModified: true,
+  lightHighlightTheme: 'vitesse-light',
+  markdownLinkExternal: true,
+  name: 'BARGS',
+  navigationLinks: {
+    GitHub: 'https://github.com/boneskull/bargs',
+    npm: 'https://www.npmjs.com/package/@boneskull/bargs',
+  },
+  out: '../docs',
+  plugin: [
+    './typedoc-plugin-bargs.js',
+    'typedoc-plugin-mdn-links',
+    'typedoc-plugin-extras',
+  ],
+  preserveWatchOutput: true,
+  searchInComments: true,
+  searchInDocuments: true,
+  tsconfig: '../tsconfig.json',
+};

.gitignore

@@ -144,3 +144,4 @@ dist/
 
 .worktrees/
 
+docs/

cspell.json

@@ -56,7 +56,8 @@
     "linkifying",
     "wallabyjs",
     "ptmux",
-    "nargs"
+    "nargs",
+    "vitesse"
   ],
   "words": [
     "bupkis",

eslint.config.js

@@ -113,7 +113,7 @@ export default defineConfig(
     },
   },
   {
-    files: ['*.js', 'scripts/**/*.js'],
+    files: ['*.js', 'scripts/**/*.js', '.config/*.js'],
     languageOptions: {
       globals: globals.node,
     },

package-lock.json

@@ -85,6 +85,8 @@
     "prettier-plugin-sort-json": "4.1.1",
     "tsx": "4.21.0",
     "typedoc": "0.28.15",
+    "typedoc-plugin-extras": "4.0.1",
+    "typedoc-plugin-mdn-links": "5.0.10",
     "typescript": "5.9.3",
     "typescript-eslint": "8.50.0",
     "zshy": "0.6.0"