菜单
How to create & maintain TypeDoc site documentation and the README for Bupkis
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | bupkis-docs |
| description | How to create & maintain TypeDoc site documentation and the README for Bupkis |
| metadata | {"category":"documentation"} |
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.
Invoke this skill when:
@bupkisAnchor, @bupkisAssertionCategory, @bupkisRedirect)CHANGELOG.md is auto-generated from commit messages and should never be manually edited. All changelog updates happen automatically during release.
Key Components:
.config/typedoc-plugin-bupkis.js) - Handles media files and dynamic redirectssite/) - Hand-written documentation pagessrc/assertion/impl/) - Source code with JSDoc tagsdocs/) - Built site (ignored by git)Build Command:
npm run docs:build
This runs TypeDoc with the strict configuration and generates the full documentation site in docs/.
Bupkis uses three custom JSDoc block tags to generate redirects for assertion documentation:
@bupkisAnchorPurpose: Specifies the anchor ID in the generated documentation page.
Format: @bupkisAnchor <anchor-id>
Example:
/**
* @bupkisAnchor unknown-to-be-a-string
*/
This creates an anchor like #unknown-to-be-a-string in the generated docs.
@bupkisAssertionCategoryPurpose: Maps the assertion to a documentation category/document.
Valid Categories:
primitives → Primitive_Assertionsstrings → String___Pattern_Assertionsnumeric → Numeric_Assertionsequality → Equality___Comparison_Assertionscollections → Collections_Assertionsobject → Object_Assertionsfunction → Function_Assertionserror → Error_Assertionsdate → Date___Time_Assertionspromise / async → Promise_Assertionssnapshot → Snapshot_Assertionsother → Other_AssertionsExample:
/**
* @bupkisAssertionCategory primitives
*/
@bupkisRedirectPurpose: (Optional) Provides a custom redirect path when it differs from the anchor.
Format: @bupkisRedirect <custom-path>
Example:
/**
* @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.
The custom plugin (.config/typedoc-plugin-bupkis.js):
Converter.EVENT_CREATE_DECLARATION during TypeDoc processingCATEGORY_DOC_MAPtypedoc-plugin-redirectassertions/<redirect-name>/ → documents/<Category_Document>#<anchor>Example Flow:
// In src/assertion/impl/sync-basic.ts
/**
* @bupkisAnchor unknown-to-be-a-string
* @bupkisAssertionCategory primitives
*/
export const stringAssertion = ...
Generated Redirect:
assertions/unknown-to-be-a-string/documents/Primitive_Assertions#unknown-to-be-a-stringWhen adding or modifying assertions in src/assertion/impl/:
Required Steps:
@bupkisAnchor and @bupkisAssertionCategory@bupkisRedirect if the URL path should differ from the anchornpm run docs:build to regenerate docsValidation:
Registered redirect for <name>: <path> ➡️ <target>Unknown category "<category>" for assertion <name>Validate Redirects:
After adding or modifying assertions, validate that redirects work correctly:
node .claude/skills/bupkis-docs/scripts/validate-redirects.js --build
This script:
What it checks:
assertions/documents/# syntaxIntegration 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:
See: references/testing-redirects.md for complete testing guide.
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
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
Problem: Redirect not generated
CATEGORY_DOC_MAP entriesProblem: Build fails
npm run docs:build for detailed error outputtypedoc.json or package.jsonProblem: Media files not copied
site/media/RendererEvent.END)scripts/ - Automation utilities for documentation tasks
validate-redirects.js - Validates documentation redirects by testing structure and optionally using Playwrightreferences/ - Detailed reference documentation
jsdoc-tags.md - Complete reference for custom JSDoc tagsbuild-process.md - Documentation build process guidetesting-redirects.md - Guide for testing redirects (see below)README.md - Index of available referencesUser: "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.