bupkis-docs
How to create & maintain TypeDoc site documentation and the README for Bupkis
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- GitHub stars: 3
- Updated: 2025-11-21
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: bupkis-docs
description: How to create & maintain TypeDoc site documentation and the README for Bupkis
metadata:
category: documentation
---
# 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 <anchor-id>`
**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 <custom-path>`
**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/<redirect-name>/` → `documents/<Category_Document>#<anchor>`
**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 <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:
```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.
```