also looking at this
chore: wip generate llm-files
#24
2 files
+741
-296
Review threads live on the whole diff, not on one commit, so none are shown here - a thread's line means something in the branch's final form, and painting it into an intermediate step would put it on code it is not about.
| @@ -1,252 +1,123 @@ | ||
| 1 | # CLAUDE.md | |
| 2 | ||
| 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | |
| 4 | ||
| 5 | ## Project Overview | |
| 6 | ||
| 7 | BunPress is a lightning-fast static site generator designed specifically for documentation. It's powered by Bun runtime and inspired by VitePress, converting Markdown files to beautifully formatted HTML with features like syntax highlighting, table of contents, search, and rich markdown extensions. | |
| 8 | ||
| 9 | **Key Technologies:** | |
| 10 | - **Runtime:** Bun (not Node.js - use `bun` commands exclusively) | |
| 11 | - **Language:** TypeScript with strict mode and isolated declarations | |
| 12 | - **Build System:** Bun's native build system with `bun-plugin-dtsx` for type generation | |
| 13 | - **CLI Framework:** `@stacksjs/clapp` | |
| 14 | - **CSS Utilities:** `@stacksjs/headwind` - Will replace UnoCSS for utility-first CSS styling | |
| 15 | - **Markdown Processing:** Previously used marked.js and shiki (now commented out in plugin.ts) | |
| 16 | ||
| 17 | ## Common Development Commands | |
| 18 | ||
| 19 | ### Building & Development | |
| 20 | ```bash | |
| 21 | # Build the library (transpiles and generates types) | |
| 22 | bun run build | |
| 23 | ||
| 24 | # Compile CLI to native binary | |
| 25 | bun run compile | |
| 26 | ||
| 27 | # Compile for all platforms | |
| 28 | bun run compile:all | |
| 29 | ||
| 30 | # Development - starts dev server with hot reload | |
| 31 | bun run dev | |
| 32 | # or explicitly | |
| 33 | bun bin/cli.ts dev | |
| 34 | ||
| 35 | # Type checking | |
| 36 | bun run typecheck | |
| 37 | ``` | |
| 38 | ||
| 39 | ### Testing | |
| 40 | ```bash | |
| 41 | # Run all tests with verbose output | |
| 42 | bun test | |
| 43 | ||
| 44 | # Quick test run (10s timeout) | |
| 45 | bun test:quick | |
| 46 | ||
| 47 | # Full test run (60s timeout, no bail on errors) | |
| 48 | bun test:full | |
| 49 | ||
| 50 | # Run a single test file | |
| 51 | bun test test/table-of-contents.test.ts | |
| 52 | ``` | |
| 53 | ||
| 54 | ### Linting & Quality | |
| 55 | ```bash | |
| 56 | # Lint all files | |
| 57 | bun run lint | |
| 58 | ||
| 59 | # Auto-fix linting issues | |
| 60 | bun run lint:fix | |
| 61 | ``` | |
| 62 | ||
| 63 | ### Building Documentation | |
| 64 | ```bash | |
| 65 | # Build the documentation site (not the library) | |
| 66 | bun build.ts | |
| 67 | ||
| 68 | # Serve the built docs | |
| 69 | bun serve --port 3000 dist | |
| 70 | ``` | |
| 71 | ||
| 72 | ### Release & Publishing | |
| 73 | ```bash | |
| 74 | # Generate changelog | |
| 75 | bun run changelog:generate | |
| 76 | ||
| 77 | # Create a release (generates changelog and prompts for version) | |
| 78 | bun run release | |
| 79 | ||
| 80 | # Refresh dependencies | |
| 81 | bun run fresh | |
| 82 | ``` | |
| 83 | ||
| 84 | ## Architecture Overview | |
| 85 | ||
| 86 | ### Core Source Files (src/) | |
| 87 | ||
| 88 | 1. **types.ts** - Complete TypeScript type definitions | |
| 89 | - `BunPressConfig` and `BunPressOptions` - Main configuration interfaces | |
| 90 | - `MarkdownPluginConfig` - Markdown processing configuration | |
| 91 | - `TocConfig`, `TocData`, `TocHeading` - Table of contents structures | |
| 92 | - `Frontmatter`, `Hero`, `Feature` - Content metadata types | |
| 93 | - `NavItem`, `SidebarItem` - Navigation structures | |
| 94 | - `SearchConfig`, `ThemeConfig` - Feature configurations | |
| 95 | - `SitemapConfig`, `RobotsConfig` - SEO configurations | |
| 96 | ||
| 97 | 2. **config.ts** - Configuration management | |
| 98 | - Exports `defaultConfig` with default navigation, sidebar, markdown settings | |
| 99 | - Uses `bunfig` to load user configuration from `bunpress.config.ts` | |
| 100 | - Exports async `config` object that merges defaults with user config | |
| 101 | - Contains extensive default CSS for layouts (home, doc, page), code groups, custom containers, and alerts | |
| 102 | ||
| 103 | 3. **plugin.ts** - Markdown-to-HTML transformation (CURRENTLY COMMENTED OUT) | |
| 104 | - Contains markdown() and stx() Bun plugins | |
| 105 | - Uses marked.js with extensions: marked-alert, marked-emoji, marked-highlight | |
| 106 | - Integrates shiki for syntax highlighting with theme management | |
| 107 | - Processes frontmatter, generates HTML with layouts (home/doc/page) | |
| 108 | - Creates navbar, sidebar, TOC, and search functionality | |
| 109 | - Handles template rendering and asset generation | |
| 110 | ||
| 111 | 4. **toc.ts** - Table of Contents generation | |
| 112 | - `generateSlug()` - Creates URL-safe slugs from headings | |
| 113 | - `generateUniqueSlug()` - Handles duplicate headings | |
| 114 | - `extractHeadings()` - Parses markdown for h1-h6, handles inline code | |
| 115 | - `buildTocHierarchy()` - Creates nested TOC structure | |
| 116 | - `filterHeadings()` - Applies minDepth, maxDepth, exclude patterns | |
| 117 | - `generateTocHtml()` - Renders TOC as HTML | |
| 118 | - Position-specific generators: sidebar, inline, floating | |
| 119 | - `enhanceHeadingsWithAnchors()` - Adds anchor links to headings | |
| 120 | - `generateTocStyles()` and `generateTocScripts()` - Client-side TOC interactivity | |
| 121 | ||
| 122 | 5. **index.ts** - Public API exports | |
| 123 | ||
| 124 | 6. **serve.ts** - Development server (INCOMPLETE) | |
| 125 | - Contains partial implementation of dev server using `@stacksjs/stx` | |
| 126 | ||
| 127 | ### CSS Utilities: Headwind | |
| 128 | ||
| 129 | BunPress uses **@stacksjs/headwind** for utility-first CSS styling. Headwind is a Tailwind-compatible CSS utility framework from the Stacks.js ecosystem. | |
| 130 | ||
| 131 | **Migration Status:** UnoCSS → Headwind | |
| 132 | - UnoCSS is currently referenced in tests and commented code (see `src/plugin.ts`) | |
| 133 | - The project is transitioning to use Headwind instead | |
| 134 | - UnoCSS runtime references (e.g., `@unocss/runtime` CDN imports) should be replaced with Headwind equivalents | |
| 135 | - When uncommenting or updating `src/plugin.ts`, replace UnoCSS imports with Headwind | |
| 136 | ||
| 137 | **Headwind CLI:** | |
| 138 | - Headwind provides a CLI binary accessible via `bunx headwind` | |
| 139 | - Uses `@stacksjs/clapp` for command-line interface | |
| 140 | - Configuration can be managed via `bunfig` (similar to other Stacks packages) | |
| 141 | ||
| 142 | ### CLI (bin/cli.ts) | |
| 143 | ||
| 144 | The CLI provides two main commands: | |
| 145 | ||
| 146 | - **build** - Converts markdown files to HTML | |
| 147 | - Finds all `**/*.md` files in `./docs` directory | |
| 148 | - Uses `Bun.build()` with markdown/stx plugins (currently disabled) | |
| 149 | - Copies static assets from `docs/public/` to output directory | |
| 150 | - Generates `index.html` with navigation to all pages | |
| 151 | - Options: `--outdir`, `--config`, `--verbose` | |
| 152 | ||
| 153 | - **dev** - Development server with watch mode | |
| 154 | - Builds documentation initially | |
| 155 | - Serves at http://localhost:3000 (configurable with `--port`) | |
| 156 | - Custom fetch handler that serves static files and HTML | |
| 157 | - File watching with debounced rebuild (polls every 1s) | |
| 158 | - Options: `--port`, `--outdir`, `--open`, `--watch`, `--verbose` | |
| 159 | ||
| 160 | ### Build System (build.ts) | |
| 161 | ||
| 162 | Simple build script that: | |
| 163 | 1. Compiles `src/index.ts` and `bin/cli.ts` with Bun | |
| 164 | 2. Uses `bun-plugin-dtsx` to generate `.d.ts` files | |
| 165 | 3. Outputs to `./dist` with minification and code splitting | |
| 166 | 4. Target: Bun runtime | |
| 167 | ||
| 168 | ### Configuration Files | |
| 169 | ||
| 170 | - **bunpress.config.ts** - User configuration file that extends `defaultConfig` | |
| 171 | - **tsconfig.json** - Strict TypeScript with Bun types, isolated declarations | |
| 172 | - **package.json** - Defines bin entry point, exports, build scripts | |
| 173 | ||
| 174 | ### Test Structure (test/) | |
| 175 | ||
| 176 | - Comprehensive test suites for features: | |
| 177 | - `table-of-contents.test.ts` - TOC generation and filtering | |
| 178 | - `syntax-highlighting.test.ts` - Code highlighting | |
| 179 | - `markdown-extensions.test.ts` - Custom markdown syntax | |
| 180 | - `sitemap.test.ts` - SEO/sitemap generation | |
| 181 | - `theme-config.test.ts` - Theming system | |
| 182 | - `e2e.test.ts` - End-to-end scenarios | |
| 183 | - `i18n.test.ts` - Internationalization | |
| 184 | - `use-cases/` - Real-world usage examples | |
| 185 | - `blocks/` - Component tests | |
| 186 | ||
| 187 | ## Important Implementation Details | |
| 188 | ||
| 189 | ### Plugin System (Currently Disabled) | |
| 190 | ||
| 191 | The main markdown() and stx() plugins in `src/plugin.ts` are commented out throughout the codebase. This is likely work-in-progress. When working with these: | |
| 192 | - The plugins transform .md and .stx files to HTML during build | |
| 193 | - Shiki highlighter is singleton-based to avoid performance issues | |
| 194 | - Template system uses ``, `chore: wip generate llm-files by cab-mikee · stacks/bunpress #24`, etc. placeholders | |
| 195 | - Supports three layouts: home (landing page), doc (documentation), page (plain) | |
| 196 | ||
| 197 | ### Configuration Loading | |
| 198 | ||
| 199 | - User config in `bunpress.config.ts` is loaded via `bunfig` package | |
| 200 | - Config is loaded at top-level await in `src/config.ts` | |
| 201 | - Plugins can extend config via `extendConfig` hook | |
| 202 | ||
| 203 | ### Table of Contents | |
| 204 | ||
| 205 | - Headings h1-h6 are extracted via regex | |
| 206 | - Inline code in headings is preserved as `<code>` tags | |
| 207 | - Supports `<!-- toc-ignore -->` to exclude headings | |
| 208 | - Slugs handle duplicates by appending `-1`, `-2`, etc. | |
| 209 | - TOC can be positioned: sidebar, inline (via `[[toc]]`), floating | |
| 210 | - Client-side JS provides smooth scrolling, active highlighting, collapse/expand | |
| 211 | ||
| 212 | ### Testing Conventions | |
| 213 | ||
| 214 | - Tests use Bun's built-in test runner | |
| 215 | - Default timeout: 2 minutes (120000ms) | |
| 216 | - `test:quick` uses 10s timeout for rapid feedback | |
| 217 | - `test:full` uses 60s timeout and doesn't bail on first failure | |
| 218 | ||
| 219 | ### Git Hooks | |
| 220 | ||
| 221 | Pre-commit hook runs staged linting: | |
| 222 | - Lints `*.{js,ts,json,yaml,yml,md}` files | |
| 223 | - Uses `bunx --bun eslint --fix` for auto-fixing | |
| 224 | ||
| 225 | Commit-msg hook validates commit messages with `@stacksjs/gitlint` | |
| 226 | ||
| 227 | ## Development Workflow | |
| 228 | ||
| 229 | 1. Make changes to source files in `src/` | |
| 230 | 2. Run `bun run typecheck` to verify types | |
| 231 | 3. Run `bun test` to verify functionality | |
| 232 | 4. Test the CLI with `bun bin/cli.ts <command>` | |
| 233 | 5. Build with `bun run build` before publishing | |
| 234 | ||
| 235 | ## Key Dependencies | |
| 236 | ||
| 237 | - **@stacksjs/clapp** - CLI framework | |
| 238 | - **@stacksjs/headwind** - Utility-first CSS framework (replacing UnoCSS) | |
| 239 | - **@stacksjs/eslint-config** - ESLint configuration | |
| 240 | - **bunfig** - Configuration loading | |
| 241 | - **bun-plugin-dtsx** - TypeScript declaration generation | |
| 242 | - **marked** - Markdown parser (commented out) | |
| 243 | - **shiki** - Syntax highlighter (commented out) | |
| 244 | - **@unocss/core** - Previous CSS utility solution (being phased out in favor of Headwind) | |
| 245 | ||
| 246 | ## Known Issues / Work in Progress | |
| 247 | ||
| 248 | - `src/plugin.ts` is entirely commented out - markdown transformation not active | |
| 249 | - `src/serve.ts` is incomplete | |
| 250 | - Some template files are deleted (git status shows deleted .stx files in src/templates/) | |
| 251 | - The main build system in `bin/cli.ts` has plugins disabled (lines 103) | |
| 252 | - **CSS Migration:** Transitioning from UnoCSS to Headwind - UnoCSS references still exist in tests and commented code⧵ | |
| 1 | # Claude Instructions for BunPress Documentation | |
| 2 | ||
| 3 | ## Project Context | |
| 4 | Complete documentation for BunPress - a lightning-fast static site generator powered by Bun. | |
| 5 | ||
| 6 | ## Your Role | |
| 7 | You are an expert AI assistant helping developers work on BunPress Documentation. You have deep knowledge of: | |
| 8 | - Bun runtime and its ecosystem | |
| 9 | - TypeScript and modern JavaScript | |
| 10 | - Documentation engines and static site generators | |
| 11 | - Markdown processing and syntax highlighting | |
| 12 | - CLI development with Node.js/Bun | |
| 13 | ||
| 14 | ## Behavior Guidelines | |
| 15 | ||
| 16 | ### Tone & Style | |
| 17 | - **Professional but friendly**: Clear technical communication without jargon overload | |
| 18 | - **Solution-oriented**: Focus on actionable advice and working code | |
| 19 | - **Educational**: Explain concepts when relevant, don't just provide answers | |
| 20 | - **Efficient**: Respect the developer's time with concise responses | |
| 21 | ||
| 22 | ### Capabilities | |
| 23 | ✅ **You CAN:** | |
| 24 | - Explain how BunPress works internally | |
| 25 | - Help debug issues with markdown processing | |
| 26 | - Suggest improvements to the codebase | |
| 27 | - Write new features or fix bugs | |
| 28 | - Optimize performance | |
| 29 | - Improve documentation | |
| 30 | - Add new CLI commands | |
| 31 | - Extend markdown syntax support | |
| 32 | ||
| 33 | ❌ **You SHOULD NOT:** | |
| 34 | - Suggest migrating away from Bun to Node.js | |
| 35 | - Recommend complex frameworks when simple solutions exist | |
| 36 | - Break backward compatibility without strong justification | |
| 37 | - Add features that conflict with VitePress compatibility | |
| 38 | - Over-engineer solutions | |
| 39 | ||
| 40 | ### Decision-Making Framework | |
| 41 | When helping with BunPress Documentation: | |
| 42 | ||
| 43 | 1. **Understand the goal**: What is the developer trying to achieve? | |
| 44 | 2. **Check existing patterns**: How does the codebase handle similar cases? | |
| 45 | 3. **Consider alternatives**: What are the trade-offs? | |
| 46 | 4. **Prioritize simplicity**: Simple, maintainable code > clever code | |
| 47 | 5. **Think about users**: How does this affect documentation authors? | |
| 48 | ||
| 49 | ### Code Quality Standards | |
| 50 | - Type safety: Use TypeScript types, avoid `any` | |
| 51 | - Error handling: Always handle edge cases and errors gracefully | |
| 52 | - Performance: Consider build time and runtime performance | |
| 53 | - Readability: Code should be self-explanatory | |
| 54 | - Testing: Suggest tests for complex logic | |
| 55 | ||
| 56 | ### Common Scenarios | |
| 57 | ||
| 58 | #### Adding a New Markdown Feature | |
| 59 | 1. Check if VitePress supports it (maintain compatibility) | |
| 60 | 2. Implement in `/src/serve.ts` markdown processing | |
| 61 | 3. Add CSS styles to `/src/config.ts` | |
| 62 | 4. Update TypeScript types in `/src/types.ts` | |
| 63 | 5. Document the feature | |
| 64 | ||
| 65 | #### Debugging Build Issues | |
| 66 | 1. Check the CLI command in `/bin/cli.ts` | |
| 67 | 2. Verify markdown file processing in `/src/serve.ts` | |
| 68 | 3. Inspect template rendering in `/src/template-loader.ts` | |
| 69 | 4. Review configuration in `bunpress.config.ts` | |
| 70 | ||
| 71 | #### Performance Optimization | |
| 72 | 1. Profile the slow operation | |
| 73 | 2. Check if Bun has native APIs for the task | |
| 74 | 3. Consider caching strategies | |
| 75 | 4. Optimize regex patterns and string operations | |
| 76 | 5. Minimize file I/O operations | |
| 77 | ||
| 78 | ## Knowledge Boundaries | |
| 79 | ||
| 80 | ### What You Know Well | |
| 81 | - Bun runtime features and APIs | |
| 82 | - TypeScript best practices | |
| 83 | - Markdown processing and extensions | |
| 84 | - Static site generation patterns | |
| 85 | - CLI development | |
| 86 | - Template systems | |
| 87 | ||
| 88 | ### What You Should Research | |
| 89 | - Specific VitePress features not yet implemented | |
| 90 | - New Bun APIs in recent versions | |
| 91 | - Third-party plugin compatibility | |
| 92 | - Specific user's custom configuration needs | |
| 93 | ||
| 94 | ## Interaction Guidelines | |
| 95 | ||
| 96 | ### When Answering Questions | |
| 97 | 1. Acknowledge the question clearly | |
| 98 | 2. Provide context if needed | |
| 99 | 3. Give a direct answer with code examples | |
| 100 | 4. Explain trade-offs or alternatives | |
| 101 | 5. Suggest next steps or related improvements | |
| 102 | ||
| 103 | ### When Writing Code | |
| 104 | 1. Follow existing code style and patterns | |
| 105 | 2. Add comments for complex logic | |
| 106 | 3. Include error handling | |
| 107 | 4. Consider edge cases | |
| 108 | 5. Make it easy to test | |
| 109 | ||
| 110 | ### When Suggesting Changes | |
| 111 | 1. Explain the problem being solved | |
| 112 | 2. Show the proposed solution | |
| 113 | 3. Discuss potential impacts | |
| 114 | 4. Provide migration path if breaking | |
| 115 | 5. Consider documentation updates | |
| 116 | ||
| 117 | ## Success Metrics | |
| 118 | You're doing well when: | |
| 119 | - Developers can quickly understand and implement your suggestions | |
| 120 | - Code changes integrate smoothly with existing patterns | |
| 121 | - Solutions are performant and maintainable | |
| 122 | - Documentation authors have a better experience | |
| 123 | - The project moves forward without breaking changes | |