configure typedoc

.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',
+};

.github/workflows/docs.yml

@@ -0,0 +1,73 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'README.md'
+      - 'site/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'README.md'
+      - 'site/**'
+      - '.github/workflows/docs.yml'
+  release:
+    types: [published]
+  # Allow manual triggering
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build documentation
+        run: npm run docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        with:
+          path: ./docs
+
+  # Deployment job
+  deploy:
+    # Only deploy on main branch pushes (not PRs) or releases
+    if: (github.ref == 'refs/heads/main' && github.event_name == 'push') || github.event_name == 'release'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.gitignore

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

.markdownlint-cli2.yaml

@@ -19,7 +19,7 @@ ignores:
   - 'CHANGELOG.md' # generated
   - '.tmp/**/*.md'
   - '.worktrees/**/*.md'
-  - 'docs/plans/**/*.md'
+  - '.plans/**/*.md'
 outputFormatters:
   - - 'markdownlint-cli2-formatter-pretty'
     - appendLink: true

README.md

@@ -181,7 +181,7 @@ All tasks
 
 ## API
 
-### `bargs.create(name, options?)`
+### bargs.create(name, options?)
 
 Create a CLI builder.
 
@@ -192,7 +192,7 @@ Create a CLI builder.
 | `epilog`      | `string` or `false` | Footer text in help (see [Epilog](#epilog)) |
 | `theme`       | `Theme`             | Help color theme (see [Theming](#theming))  |
 
-### `.globals(parser)`
+### .globals(parser)
 
 Set global options and transforms that apply to all commands.
 
@@ -201,7 +201,7 @@ bargs.create('my-cli').globals(opt.options({ verbose: opt.boolean() }));
 // ...
 ```
 
-### `.command(name, parser, handler, description?)`
+### .command(name, parser, handler, description?)
 
 Register a command. The handler receives merged global + command types.
 
@@ -217,7 +217,9 @@ Register a command. The handler receives merged global + command types.
 )
 ```
 
-### `.defaultCommand(name)` or `.defaultCommand(parser, handler)`
+### .defaultCommand(name)
+
+> Or `.defaultCommand(parser, handler)`
 
 Set the command that runs when no command is specified.
 
@@ -232,7 +234,7 @@ Set the command that runs when no command is specified.
 )
 ```
 
-### `.parse(args?)` / `.parseAsync(args?)`
+### .parse(args?) / .parseAsync(args?)
 
 Parse arguments and execute handlers.
 

cspell.json

@@ -25,8 +25,9 @@
     "coverage",
     "dist",
     "docs",
+    ".plans",
     "node_modules",
-    "worktrees",
+    ".worktrees",
     ".git"
   ],
   "ignoreRandomStrings": true,
@@ -55,7 +56,9 @@
     "linkifying",
     "wallabyjs",
     "ptmux",
-    "nargs"
+    "nargs",
+    "vitesse",
+    "realfavicongenerator"
   ],
   "words": [
     "bupkis",
@@ -65,6 +68,7 @@
     "linkify",
     "positionals",
     "subcommand",
-    "subcommands"
+    "subcommands",
+    "navigations"
   ]
 }

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.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"