# Bupkis Docs > How to create & maintain TypeDoc site documentation and the README for Bupkis - Skill: `majiayu000/bupkis-docs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds add majiayu000/bupkis-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/bupkis-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: majiayu000 (https://skillmd.com/u/majiayu000) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/majiayu000/bupkis-docs --- # Bupkis Documentation ## Overview This skill provides guidance for creating and maintaining the Bupkis documentation site, which uses TypeDoc with custom plugins for automated redirect generation and media file management. ## When to Use Invoke this skill when: - Updating the TypeDoc site documentation - Modifying README.md structure or content - Adding new assertion implementations that need documentation - Building or validating the documentation site - Fixing documentation build issues - Working with custom JSDoc tags (`@bupkisAnchor`, `@bupkisAssertionCategory`, `@bupkisRedirect`) ## Important: Do Not Edit **CHANGELOG.md is auto-generated** from commit messages and should never be manually edited. All changelog updates happen automatically during release. ## Architecture Overview **Key Components:** - **TypeDoc** - API documentation generator - **Custom Plugin** (`.config/typedoc-plugin-bupkis.js`) - Handles media files and dynamic redirects - **Site Structure** (`site/`) - Hand-written documentation pages - **Assertion Implementations** (`src/assertion/impl/`) - Source code with JSDoc tags - **Generated Output** (`docs/`) - Built site (ignored by git) ## Building Documentation **Build Command:** ```bash npm run docs:build ``` This runs TypeDoc with the strict configuration and generates the full documentation site in `docs/`. ## Custom JSDoc Tags System Bupkis uses three custom JSDoc block tags to generate redirects for assertion documentation: ### `@bupkisAnchor` **Purpose:** Specifies the anchor ID in the generated documentation page. **Format:** `@bupkisAnchor ` **Example:** ```typescript /** * @bupkisAnchor unknown-to-be-a-string */ ``` This creates an anchor like `#unknown-to-be-a-string` in the generated docs. ### `@bupkisAssertionCategory` **Purpose:** Maps the assertion to a documentation category/document. **Valid Categories:** - `primitives` → `Primitive_Assertions` - `strings` → `String___Pattern_Assertions` - `numeric` → `Numeric_Assertions` - `equality` → `Equality___Comparison_Assertions` - `collections` → `Collections_Assertions` - `object` → `Object_Assertions` - `function` → `Function_Assertions` - `error` → `Error_Assertions` - `date` → `Date___Time_Assertions` - `promise` / `async` → `Promise_Assertions` - `snapshot` → `Snapshot_Assertions` - `other` → `Other_Assertions` **Example:** ```typescript /** * @bupkisAssertionCategory primitives */ ``` ### `@bupkisRedirect` **Purpose:** (Optional) Provides a custom redirect path when it differs from the anchor. **Format:** `@bupkisRedirect ` **Example:** ```typescript /** * @bupkisAnchor function-to-throw-any * @bupkisAssertionCategory function * @bupkisRedirect to-throw */ ``` This creates a redirect from `assertions/to-throw/` → `documents/Function_Assertions#function-to-throw-any`. ## How Redirects Work The custom plugin (`.config/typedoc-plugin-bupkis.js`): 1. **Listens** to `Converter.EVENT_CREATE_DECLARATION` during TypeDoc processing 2. **Inspects** JSDoc block tags on variable declarations with assertion types 3. **Validates** that the category exists in `CATEGORY_DOC_MAP` 4. **Registers** redirects using `typedoc-plugin-redirect` 5. **Format:** `assertions//` → `documents/#` **Example Flow:** ```typescript // In src/assertion/impl/sync-basic.ts /** * @bupkisAnchor unknown-to-be-a-string * @bupkisAssertionCategory primitives */ export const stringAssertion = ... ``` **Generated Redirect:** - Path: `assertions/unknown-to-be-a-string/` - Target: `documents/Primitive_Assertions#unknown-to-be-a-string` ## Updating Assertion Documentation When adding or modifying assertions in `src/assertion/impl/`: **Required Steps:** 1. Add JSDoc comment with `@bupkisAnchor` and `@bupkisAssertionCategory` 2. Verify the category matches one of the valid categories 3. (Optional) Add `@bupkisRedirect` if the URL path should differ from the anchor 4. Run `npm run docs:build` to regenerate docs 5. Check build output for redirect registration logs 6. Verify the redirect works in the generated site **Validation:** - Plugin logs: `Registered redirect for : ➡️ ` - Warning for unknown categories: `Unknown category "" for assertion ` ## Testing Documentation **Validate Redirects:** After adding or modifying assertions, validate that redirects work correctly: ```bash node .claude/skills/bupkis-docs/scripts/validate-redirects.js --build ``` This script: 1. Builds the documentation 2. Parses build logs to extract registered redirects 3. Validates redirect structure and format 4. Reports any invalid redirects **What it checks:** - ✓ Redirect paths start with `assertions/` - ✓ Document paths start with `documents/` - ✓ Anchors are present when using `#` syntax - ✓ All registered redirects follow expected format **Integration with Playwright:** The script is designed to work with Claude Code's Playwright MCP server for end-to-end testing. When invoked by Claude, it can: - Serve documentation locally - Navigate to redirect URLs - Verify redirects resolve to correct target pages - Check that anchors exist on target pages **See:** `references/testing-redirects.md` for complete testing guide. ## Site Structure **Hand-Written Content** (`site/`): ``` site/ ├── about/ - About pages ├── assertions/ - Assertion documentation ├── guide/ - User guides ├── media/ - Images, logos (copied to docs/media/) └── reference/ - Reference documentation ``` **Generated Output** (`docs/` - gitignored): ``` docs/ ├── assets/ - TypeDoc-generated CSS/JS ├── documents/ - Generated API documentation ├── media/ - Copied from site/media/ └── [other pages] - Generated HTML pages ``` ## Media Files The plugin automatically copies all files from `site/media/` to `docs/media/` after rendering completes. **Log Output:** ``` Will copy all files in site/media/ to docs/media/ Copied site/media/logo.png to docs/media/logo.png ``` ## Troubleshooting **Problem:** Redirect not generated - **Check:** JSDoc tags are present and correctly formatted - **Check:** Category name matches `CATEGORY_DOC_MAP` entries - **Check:** Variable is exported and has an assertion type - **Review:** Build logs for warnings about unknown categories **Problem:** Build fails - **Check:** Run `npm run docs:build` for detailed error output - **Check:** TypeDoc configuration in `typedoc.json` or package.json - **Check:** Plugin is loaded correctly in TypeDoc config **Problem:** Media files not copied - **Check:** Files exist in `site/media/` - **Check:** Build completed successfully (copy happens at `RendererEvent.END`) - **Review:** Build logs for copy confirmation messages ## Bundled Resources **scripts/** - Automation utilities for documentation tasks - `validate-redirects.js` - Validates documentation redirects by testing structure and optionally using Playwright **references/** - Detailed reference documentation - `jsdoc-tags.md` - Complete reference for custom JSDoc tags - `build-process.md` - Documentation build process guide - `testing-redirects.md` - Guide for testing redirects (see below) - `README.md` - Index of available references ## Examples ``` User: "Add documentation for the new isEmpty assertion" Claude: I'll help you add the JSDoc tags for documentation. Based on the assertion implementation, I'll add: - @bupkisAnchor array-to-be-empty - @bupkisAssertionCategory collections Then rebuild the docs to verify the redirect is registered correctly. ``` ``` User: "The redirect for 'to throw' isn't working" Claude: Let me check the JSDoc tags in the assertion implementation. I'll verify: 1. The @bupkisRedirect tag is set to "to-throw" 2. The @bupkisAnchor matches the expected anchor 3. The category is valid in CATEGORY_DOC_MAP Then rebuild and check the logs for redirect registration. ``` ``` User: "Update the README to add the new feature section" Claude: I'll update README.md following the existing structure. After making changes, I'll run `npm run docs:build` to ensure the documentation site builds correctly with the updated content. ```