How to create & maintain TypeDoc site documentation and the README for Bupkis
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.
npx skills add boneskull/bupkis-docs下载完整 Skill 目录，包含 SKILL.md 及所有相关文件
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer