@knowcode/doc-builder 1.5.21 → 1.5.23

package/.claude/settings.local.json

@@ -28,7 +28,8 @@
       "Bash(git log:*)",
       "Bash(mkdir:*)",
       "Bash(cp:*)",
-      "Bash(./publish.sh)"
+      "Bash(./publish.sh)",
+      "Bash(mv:*)"
     ],
     "deny": []
   }

package/CLAUDE.md

@@ -8,6 +8,7 @@ This file provides comprehensive guidance for Claude Code when working with the
 **Version**: 1.4.3  
 **Purpose**: Transform markdown documentation into beautiful, searchable static HTML sites with a Notion-inspired design  
 **NPM Package**: Published at https://www.npmjs.com/package/@knowcode/doc-builder
+**GitHub Repository**: https://github.com/wapdat/doc-builder
 
 ### Key Features
 - 📝 **Markdown to HTML conversion** with syntax highlighting and mermaid diagram support
@@ -19,305 +20,10 @@ This file provides comprehensive guidance for Claude Code when working with the
 - 📱 **Fully responsive** design
 - 🔧 **Zero configuration** - works with sensible defaults
 
-## Repository Structure
+## Documentation Guidelines
 
-```
-doc-builder/
-├── assets/                 # Static assets (CSS, JS)
-│   ├── css/
-│   │   └── notion-style.css   # Main stylesheet
-│   └── js/
-│       ├── main.js            # Client-side functionality
-│       └── auth.js            # Authentication logic
-├── lib/                   # Core library files
-│   ├── builder.js         # Main build orchestrator
-│   ├── core-builder.js    # Core build logic & HTML generation
-│   ├── config.js          # Configuration management
-│   ├── deploy.js          # Vercel deployment logic
-│   └── dev-server.js      # Development server
-├── scripts/               # NPM scripts
-│   ├── npx-runner.js      # NPX entry point
-│   └── setup.js           # Post-install setup
-├── templates/             # HTML templates
-├── cli.js                 # CLI entry point
-├── index.js               # Programmatic API entry point
-├── package.json           # NPM configuration
-├── CHANGELOG.md           # Version history
-└── README.md              # User documentation
-```
-
-## Technical Architecture
-
-### Core Components
-
-1. **CLI Interface** (`cli.js`)
-   - Commander.js based CLI with commands: build, dev, deploy, init
-   - Extensive help documentation built-in
-   - Interactive prompts for Vercel deployment
-
-2. **Build System** (`lib/core-builder.js`)
-   - Scans for markdown files recursively
-   - Extracts titles and summaries for navigation tooltips
-   - Generates HTML with embedded navigation
-   - Copies static assets
-   - Auto-generates README.md if missing
-
-3. **Navigation System**
-   - Automatically builds hierarchical navigation from folder structure
-   - Collapsible folder sections
-   - Active page highlighting
-   - Tooltips showing document summaries
-   - Search/filter functionality
-
-4. **Deployment System** (`lib/deploy.js`)
-   - Integrated Vercel deployment
-   - Automatic project setup for first-time users
-   - Production and preview deployments
-   - vercel.json generation for proper routing
-
-### Key Functions
-
-#### core-builder.js
-- `buildDocumentation(config)` - Main build orchestrator
-- `processMarkdownFile(file, output, allFiles, config)` - Process individual markdown files
-- `extractSummary(content)` - Extract document summary for tooltips
-- `buildNavigationStructure(files, currentFile)` - Build navigation tree
-- `generateHTML(title, content, navigation, currentPath, config)` - Generate final HTML
-
-#### deploy.js
-- `deployToVercel(config, isProduction)` - Deploy to Vercel
-- `setupVercelProject(config)` - First-time Vercel setup
-- `prepareDeployment(config)` - Prepare files for deployment
-
-## Configuration
-
-### Default Configuration (doc-builder.config.js)
-```javascript
-module.exports = {
-  siteName: 'Documentation',
-  siteDescription: 'Documentation site',
-  docsDir: 'docs',          // Input directory
-  outputDir: 'html',        // Output directory
-  features: {
-    authentication: false,   // Enable password protection
-    changelog: true,        // Auto-generate changelog
-    mermaid: true,          // Mermaid diagram support
-    darkMode: true          // Dark mode toggle
-  }
-};
-```
-
-### Presets
-The tool supports presets for common configurations. Currently available:
-- `notion-inspired` - Default Notion-like styling
-
-## Common Commands
-
-### Development
-```bash
-# Install dependencies
-npm install
-
-# Run locally (development)
-node cli.js dev
-
-# Build documentation
-node cli.js build
-
-# Deploy to Vercel
-node cli.js deploy
-```
-
-### Testing
-```bash
-# Pack for local testing
-npm pack
-
-# Test in another project
-npm install /path/to/doc-builder/knowcode-doc-builder-1.4.3.tgz
-```
-
-### Publishing
-```bash
-# Update version in package.json
-npm version patch  # or minor/major
-
-# Publish to npm
-npm publish
-
-# Tag release
-git tag v1.4.3
-git push origin v1.4.3
-```
-
-## Recent Changes & Known Issues
-
-### Version 1.4.3 (2025-07-20)
-- Fixed tooltip functionality by restoring extractSummary function
-- Removed unwanted Home link from sidebar
-- Fixed excessive left padding issue caused by JavaScript margin-left assignments
-
-### Version 1.4.2 (2025-01-20)
-- Fixed content layout to use flexbox properly
-- Removed dynamic margin-left JavaScript that was overriding CSS
-
-### Known Issues
-- NPX caching can cause older versions to run - use `npm install` instead
-- Global npm packages can interfere - check with `which doc-builder`
-
-## Development Guidelines
-
-### Code Style
-- Use ES6+ features where appropriate
-- Maintain consistent error handling with try/catch blocks
-- Use chalk for colored console output
-- Use ora for loading spinners
-- Clear, descriptive variable and function names
-
-### Testing Changes
-1. Build the package: `npm pack`
-2. Test in a real project before publishing
-3. Verify all commands work: build, dev, deploy
-4. Check generated HTML renders correctly
-5. Test Vercel deployment
-
-### Git Workflow
-1. Create feature branch from main
-2. Make changes with clear commits
-3. Update CHANGELOG.md
-4. Update version in package.json
-5. Create PR with description of changes
-6. After merge, publish to npm
-
-### Publishing Checklist
-- [ ] Update version in package.json
-- [ ] Update CHANGELOG.md with changes
-- [ ] Run `npm pack` and test locally
-- [ ] Commit changes with version bump
-- [ ] Run `npm publish`
-- [ ] Create git tag for version
-- [ ] Push tag to GitHub
-
-## Debugging Tips
-
-### Common Issues
-
-1. **Build not finding files**
-   - Check docsDir configuration
-   - Ensure markdown files have .md extension
-   - Check for hidden directories (start with .)
-
-2. **Vercel deployment fails**
-   - Ensure Vercel CLI is installed globally
-   - Check authentication with `vercel whoami`
-   - Verify Root Directory is empty in Vercel settings
-
-3. **Styles not loading**
-   - Check asset paths in generated HTML
-   - Verify assets are copied to output directory
-   - Check browser console for 404 errors
-
-4. **Navigation not showing files**
-   - Check file paths don't contain special characters
-   - Verify markdown files are valid
-   - Check console for JavaScript errors
-
-### Debug Mode
-Set environment variables for more verbose output:
-```bash
-DEBUG=doc-builder* node cli.js build
-```
-
-## Integration with Other Projects
-
-### As NPM Dependency
-```json
-{
-  "devDependencies": {
-    "@knowcode/doc-builder": "^1.4.3"
-  },
-  "scripts": {
-    "build:docs": "doc-builder build",
-    "dev:docs": "doc-builder dev",
-    "deploy:docs": "doc-builder deploy"
-  }
-}
-```
-
-### Programmatic Usage
-```javascript
-const { build } = require('@knowcode/doc-builder');
-
-const config = {
-  siteName: 'My Docs',
-  docsDir: './documentation',
-  outputDir: './dist'
-};
-
-build(config).then(() => {
-  console.log('Build complete!');
-});
-```
-
-## Architecture Decisions
-
-### Why Flexbox for Layout?
-- Avoids JavaScript-based resizing issues
-- Better responsive behavior
-- Simpler to maintain
-- Native browser support
-
-### Why Extract Git History?
-- This project was extracted from a monorepo using `git filter-branch`
-- Preserves commit history for better understanding of evolution
-- Allows independent versioning and releases
-
-### Why Notion-Inspired Design?
-- Clean, modern interface
-- Familiar to many users
-- Good information hierarchy
-- Excellent readability
-
-## Future Enhancements
-
-### Planned Features
-- [ ] Full-text search functionality
-- [ ] PDF export capability
-- [ ] Multiple theme support
-- [ ] Plugin system for extensions
-- [ ] Improved mermaid diagram styling
-- [ ] Better mobile navigation UX
-
-### Technical Debt
-- [ ] Add comprehensive test suite
-- [ ] Refactor CSS to use CSS modules or styled-components
-- [ ] Improve build performance for large documentation sets
-- [ ] Add progress indicators for long builds
-
-## Support & Contributing
-
-### Getting Help
-- File issues at: https://github.com/your-username/doc-builder/issues
-- Check existing issues before creating new ones
-- Include version number and error messages
-
-### Contributing
-1. Fork the repository
-2. Create feature branch
-3. Add tests if applicable
-4. Update documentation
-5. Submit pull request
-
-## License
-
-MIT License - See LICENSE file for details
-
-### NPM Features Documentation
-- When we add new features - add it to the NPM documented bullet point features - if its a big feature give it a section
-
-## Publishing Memories
-- Note how to publish the npm and that there is a @publish.sh script to help
-
----
-
-**Note**: This project was extracted from the cybersolstice monorepo on 2025-07-21 with full git history preservation.
+- For this project documentation, do not include in each document:
+  - Generated timestamp
+  - Status field
+  - Verification status
+- We do not want these metadata fields in the project documentation

package/CONTRIBUTING.md

@@ -0,0 +1,148 @@
+# Contributing to Doc Builder
+
+First off, thank you for considering contributing to Doc Builder! It's people like you that make Doc Builder such a great tool.
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+
+* **Use a clear and descriptive title**
+* **Describe the exact steps to reproduce the problem**
+* **Provide specific examples to demonstrate the steps**
+* **Describe the behavior you observed and expected**
+* **Include screenshots if relevant**
+* **Include your environment details** (OS, Node.js version, npm version)
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:
+
+* **Use a clear and descriptive title**
+* **Provide a detailed description of the suggested enhancement**
+* **Provide specific examples to demonstrate how it would work**
+* **Describe the current behavior and expected behavior**
+* **Explain why this enhancement would be useful**
+
+### Your First Code Contribution
+
+Unsure where to begin? You can start by looking through these issues:
+
+* `good first issue` - issues which should only require a few lines of code
+* `help wanted` - issues which need extra attention
+
+### Pull Requests
+
+1. Fork the repo and create your branch from `main`
+2. If you've added code that should be tested, add tests
+3. If you've changed APIs, update the documentation
+4. Ensure the test suite passes
+5. Make sure your code follows the existing style
+6. Issue that pull request!
+
+## Development Process
+
+1. **Setup your environment**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/doc-builder.git
+   cd doc-builder
+   npm install
+   ```
+
+2. **Create a branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make your changes**
+   - Write code
+   - Add tests if applicable
+   - Update documentation
+
+4. **Test your changes**
+   ```bash
+   npm test
+   npm run build
+   npm run dev
+   ```
+
+5. **Commit your changes**
+   ```bash
+   git add .
+   git commit -m "feat: add amazing feature"
+   ```
+
+   We follow [Conventional Commits](https://www.conventionalcommits.org/):
+   - `feat:` new feature
+   - `fix:` bug fix
+   - `docs:` documentation changes
+   - `style:` formatting, missing semicolons, etc
+   - `refactor:` code change that neither fixes a bug nor adds a feature
+   - `test:` adding missing tests
+   - `chore:` maintain
+
+6. **Push to your fork**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. **Open a Pull Request**
+
+## Style Guide
+
+### JavaScript Style Guide
+
+* Use ES6+ features where appropriate
+* 2 spaces for indentation
+* Use semicolons
+* Use `const` and `let`, avoid `var`
+* Use meaningful variable names
+* Add comments for complex logic
+
+### Documentation Style Guide
+
+* Use Markdown for all documentation
+* Include code examples where relevant
+* Keep line length to 80 characters where possible
+* Use present tense ("Add feature" not "Added feature")
+
+## Testing
+
+* Write tests for new features
+* Ensure all tests pass before submitting PR
+* Aim for high code coverage
+* Test edge cases
+
+## Project Structure
+
+```
+doc-builder/
+├── assets/          # Static assets
+├── lib/             # Core library code
+├── scripts/         # Build and utility scripts
+├── templates/       # HTML templates
+├── test/           # Test files
+├── docs/           # Documentation
+└── cli.js          # CLI entry point
+```
+
+## Release Process
+
+Maintainers will handle releases, but for reference:
+
+1. Update version in `package.json`
+2. Update `CHANGELOG.md`
+3. Commit changes
+4. Tag release
+5. Push to npm
+
+## Questions?
+
+Feel free to open an issue with your question or reach out to the maintainers.
+
+Thank you for contributing! 🎉

package/GITHUB_SETUP.md

@@ -0,0 +1,203 @@
+# GitHub Repository Setup Instructions
+
+This guide will walk you through setting up the doc-builder project on GitHub.
+
+## Prerequisites
+
+- GitHub account
+- Git installed locally
+- Command line access
+
+## Step 1: Create GitHub Repository
+
+1. Go to https://github.com/new
+2. Repository settings:
+   - **Repository name**: `doc-builder`
+   - **Description**: `Transform markdown into beautiful documentation sites with one-command Vercel deployment`
+   - **Public** repository (for open source)
+   - **DO NOT** initialize with README, .gitignore, or license (we already have these)
+
+3. Click "Create repository"
+
+## Step 2: Update Local Git Configuration
+
+First, let's check the current remote:
+
+```bash
+git remote -v
+```
+
+You'll see it points to a local directory. We need to change this to GitHub.
+
+## Step 3: Add GitHub as Remote
+
+Since your repository is at https://github.com/wapdat/doc-builder:
+
+```bash
+# Remove the existing remote
+git remote remove origin
+
+# Add GitHub as the new origin
+git remote add origin https://github.com/wapdat/doc-builder.git
+
+# Verify the change
+git remote -v
+```
+
+## Step 4: Push to GitHub
+
+```bash
+# Push all branches and tags
+git push -u origin main
+git push --tags
+```
+
+## Step 5: Configure Repository Settings
+
+On GitHub, go to Settings and configure:
+
+### General Settings
+- **Features**: Enable Issues, Projects, and Discussions
+- **Pull Requests**: Allow merge commits, squash merging, and rebase merging
+
+### Branch Protection (Settings → Branches)
+For the `main` branch:
+- [ ] Require pull request reviews before merging
+- [ ] Dismiss stale pull request approvals
+- [ ] Require status checks to pass
+- [ ] Include administrators
+
+### Pages (optional, for documentation)
+- Source: Deploy from a branch
+- Branch: main
+- Folder: /docs
+
+### Topics
+Add these topics to help people discover your project:
+- `documentation`
+- `markdown`
+- `static-site-generator`
+- `vercel`
+- `notion`
+- `developer-tools`
+- `nodejs`
+- `npm-package`
+
+## Step 6: Add Badges to README
+
+Update your README.md to include GitHub badges:
+
+```markdown
+[![npm version](https://img.shields.io/npm/v/@knowcode/doc-builder)](https://www.npmjs.com/package/@knowcode/doc-builder)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/wapdat/doc-builder)](https://github.com/wapdat/doc-builder/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/wapdat/doc-builder)](https://github.com/wapdat/doc-builder/issues)
+```
+
+## Step 7: Create Initial Release
+
+1. Go to https://github.com/wapdat/doc-builder/releases
+2. Click "Create a new release"
+3. Tag version: `v1.5.21`
+4. Release title: `v1.5.21 - Stable Release`
+5. Description:
+   ```markdown
+   ## Doc Builder v1.5.21
+   
+   First public release of Doc Builder on GitHub!
+   
+   ### Features
+   - ✨ Notion-inspired design
+   - 🚀 One-command Vercel deployment
+   - 🔍 Built-in search functionality
+   - 🌓 Dark mode support
+   - 📊 Mermaid diagram integration
+   - 🔐 Password protection option
+   
+   ### Installation
+   ```bash
+   npm install -g @knowcode/doc-builder
+   ```
+   
+   ### Quick Start
+   ```bash
+   npx @knowcode/doc-builder@latest deploy
+   ```
+   ```
+6. Click "Publish release"
+
+## Step 8: Set Up GitHub Actions (Optional)
+
+Create `.github/workflows/npm-publish.yml`:
+
+```yaml
+name: Publish to NPM
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm test
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+```
+
+To use this:
+1. Get npm token from https://www.npmjs.com/settings/YOUR_NPM_USERNAME/tokens
+2. Add as secret in GitHub: Settings → Secrets → Actions → New repository secret
+3. Name: `NPM_TOKEN`
+
+## Step 9: Update Package.json
+
+Add GitHub repository info to package.json:
+
+```json
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/wapdat/doc-builder.git"
+},
+"bugs": {
+  "url": "https://github.com/wapdat/doc-builder/issues"
+},
+"homepage": "https://github.com/wapdat/doc-builder#readme"
+```
+
+## Step 10: Announce the Repository
+
+Once everything is set up:
+
+1. Update the demo site to link to GitHub
+2. Update npm package to include repository link
+3. Share on social media
+4. Submit to awesome lists
+5. Post in relevant communities
+
+## Maintenance Tips
+
+- Respond to issues promptly
+- Review pull requests within a week
+- Keep dependencies updated
+- Tag releases consistently
+- Maintain a clear roadmap
+- Acknowledge contributors
+
+## Next Steps
+
+1. [ ] Create a GitHub Project board for roadmap
+2. [ ] Set up GitHub Discussions for community
+3. [ ] Add GitHub Sponsors if desired
+4. [ ] Create GitHub Wiki for extended docs
+5. [ ] Set up automated testing with GitHub Actions
+
+The repository is configured for https://github.com/wapdat/doc-builder

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KnowCode Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.