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:

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 <anchor-id>

Example:

/**
 * @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:

/**
 * @bupkisAssertionCategory primitives
 */

@bupkisRedirect

Purpose: (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

.

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/<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:

• 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 <name>: <path> ➡️ <target>

• Warning for unknown categories:

  Unknown category "<category>" for assertion <name>

Testing Documentation

Validate Redirects:

After adding or modifying assertions, validate that redirects work correctly:

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.