{"id":29813338,"url":"https://github.com/wapdat/doc-builder","last_synced_at":"2025-07-28T19:02:10.291Z","repository":{"id":306050152,"uuid":"1024453169","full_name":"wapdat/doc-builder","owner":"wapdat","description":" Transform markdown into beautiful documentation sites with one-command Vercel deployment","archived":false,"fork":false,"pushed_at":"2025-07-22T18:12:08.000Z","size":1546,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-23T12:12:40.950Z","etag":null,"topics":["ai","developer-tools","markdown","nodejs","notion","npm-packages","static-site-generator","vercel"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wapdat.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-22T18:10:32.000Z","updated_at":"2025-07-22T18:18:40.000Z","dependencies_parsed_at":"2025-07-23T12:12:45.017Z","dependency_job_id":"533c84b6-0410-4364-ab88-bd66317ca385","html_url":"https://github.com/wapdat/doc-builder","commit_stats":null,"previous_names":["wapdat/doc-builder"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/wapdat/doc-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapdat%2Fdoc-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapdat%2Fdoc-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapdat%2Fdoc-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapdat%2Fdoc-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wapdat","download_url":"https://codeload.github.com/wapdat/doc-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapdat%2Fdoc-builder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267329223,"owners_count":24069819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","developer-tools","markdown","nodejs","notion","npm-packages","static-site-generator","vercel"],"created_at":"2025-07-28T19:00:41.661Z","updated_at":"2025-07-28T19:02:10.259Z","avatar_url":"https://github.com/wapdat.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @knowcode/doc-builder\n\nBeautiful documentation with the least effort possible. A zero-configuration documentation builder that transforms markdown files into stunning static sites.\n\n[![npm version](https://img.shields.io/npm/v/@knowcode/doc-builder)](https://www.npmjs.com/package/@knowcode/doc-builder)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/wapdat/doc-builder)](https://github.com/wapdat/doc-builder/stargazers)\n[![GitHub issues](https://img.shields.io/github/issues/wapdat/doc-builder)](https://github.com/wapdat/doc-builder/issues)\n\n\u003cdiv align=\"center\"\u003e\n\n🔗 **[View Live Example](https://doc-builder-delta.vercel.app)** | 📦 **[NPM Package](https://www.npmjs.com/package/@knowcode/doc-builder)** | 📚 **[Documentation](https://doc-builder-delta.vercel.app)**\n\n### Quick Start\n```bash\nnpx @knowcode/doc-builder@latest deploy\n```\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Core Value Proposition\n\n| **Problem** | **Solution** |\n|------------|-------------|\n| Complex documentation setup | Zero configuration needed |\n| Deployment headaches | One-command Vercel deployment |\n| Expensive hosting | Free tier with Vercel |\n| Ugly default themes | Beautiful Notion-inspired design |\n| Manual navigation | Auto-generated from folder structure |\n\n## What It Does\n\n@knowcode/doc-builder transforms your markdown files into beautiful, static documentation websites. It:\n\n- **Scans** your markdown files and automatically generates navigation\n- **Converts** markdown to HTML with syntax highlighting and diagram support\n- **Styles** everything with a clean, Notion-inspired theme\n- **Deploys** to Vercel with a single command - leveraging their generous free tier\n- **Provides** optional features like authentication, dark mode, and changelog generation, SEO\n\nPerfect for project documentation, API references, knowledge bases, or any content written in markdown.\n\n## Why Vercel?\n\nWe chose Vercel as our deployment platform because of their **generous free tier** that includes:\n- Unlimited personal projects\n- Automatic HTTPS certificates\n- Global CDN for fast loading worldwide\n- Custom domains support\n- Automatic deployments from Git\n- No credit card required\n\nThis aligns perfectly with our mission: beautiful documentation should be accessible to everyone, without worrying about hosting costs or complex server management.\n\n## ✨ Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🛠️ Core Features\n- 🚀 **Zero Configuration** - Works out of the box\n- 📝 **Markdown Support** - Full GitHub Flavored Markdown\n- 🎨 **Beautiful Theme** - Notion-inspired design\n- 📦 **Self-Contained** - No setup required\n- 🤖 **Claude Code Ready** - AI-optimized workflows\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🎯 Advanced Features  \n- 🔍 **SEO Optimized** - Meta tags \u0026 structured data\n- 🔐 **Optional Auth** - Supabase authentication (opt-in)\n- 📊 **Mermaid Diagrams** - Built-in diagram support\n- 🌙 **Dark Mode** - Automatic theme switching\n- ☁️ **Vercel Deploy** - One-command deployment\n- ✅ **Google Verification** - Search Console ready\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## 📋 Prerequisites\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### System Requirements\n\n**Node.js** version 14.0 or higher is required to run doc-builder.\n\nTo check if you have Node.js installed:\n```bash\nnode --version\n```\n\nIf you see a version number (e.g., `v18.17.0`), you're ready to go!\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### Installing Node.js \u0026 npm\n\n**🍎 macOS**\n- **Recommended**: [Download from nodejs.org](https://nodejs.org/)\n- **Alternative**: Using Homebrew\n  ```bash\n  brew install node\n  ```\n\n**🪟 Windows**\n- **Recommended**: [Download from nodejs.org](https://nodejs.org/)\n- **Alternative**: Using Chocolatey\n  ```bash\n  choco install nodejs\n  ```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Quick Installation Links\n\n| Platform | Official Installer | Package Manager |\n|----------|-------------------|-----------------|\n| **macOS** | [Download .pkg](https://nodejs.org/en/download/) | `brew install node` |\n| **Windows** | [Download .msi](https://nodejs.org/en/download/) | `choco install nodejs` |\n| **Linux** | [Download options](https://nodejs.org/en/download/) | `apt install nodejs` or `yum install nodejs` |\n\n\u003e 💡 **Note**: npm (Node Package Manager) is included with Node.js installation automatically.\n\n## 🚀 Getting Started\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### Option 1: NPX (No Installation)\n```bash\n# Deploy to Vercel\nnpx @knowcode/doc-builder@latest deploy\n\n# Build static HTML\nnpx @knowcode/doc-builder@latest build\n\n# Show help\nnpx @knowcode/doc-builder@latest\n```\n*Perfect for trying it out!*\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### Option 2: NPM Install\n```bash\n# Install as dev dependency\nnpm install --save-dev @knowcode/doc-builder@latest\n\n# Use shorter commands\ndoc-builder deploy\ndoc-builder build\ndoc-builder --help\n```\n*Better for regular use \u0026 offline access*\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## First-Time Vercel Deployment\n\nThe deployment process is now simpler than ever:\n\n1. Run `npx @knowcode/doc-builder@latest deploy`\n2. Answer a few simple questions (project name, etc.)\n3. Vercel CLI automatically detects and configures everything\n4. Get your live URL in seconds!\n\n### Making Your Docs Public\n\nAfter deployment, if you want public access:\n\n1. Go to [Vercel Dashboard](https://vercel.com/dashboard)\n2. Click your project → Settings → Deployment Protection\n3. Set **Vercel Authentication** to **Disabled**\n4. Save changes\n\nSee the [First-Time Setup Guide](docs/vercel-first-time-setup-guide.md) for a complete walkthrough.\n\n## Configuration (optional - can be managed with CLI)\n\nCreate `doc-builder.config.js` in your project root:\n\n```javascript\nmodule.exports = {\n  // Directories\n  docsDir: 'docs',\n  outputDir: 'html',\n  \n  // Site info\n  siteName: '@knowcode/doc-builder',\n  siteDescription: 'Transform markdown into beautiful documentation',\n  favicon: '✨',  // Can be emoji or path to image file\n  \n  // Production URL (optional)\n  productionUrl: 'https://my-docs.vercel.app',  // Custom URL to display after deployment\n  \n  // Features\n  features: {\n    authentication: 'supabase',  // or false for no auth\n    changelog: true,\n    mermaid: true,\n    darkMode: true\n  },\n  \n  // Supabase Authentication\n  auth: {\n    supabaseUrl: process.env.SUPABASE_URL,\n    supabaseAnonKey: process.env.SUPABASE_ANON_KEY,\n    siteId: process.env.DOC_SITE_ID\n  }\n};\n```\n\n### 🔐 Authentication Setup\n\nFor secure documentation sites, use Supabase authentication:\n\n```bash\n# Initialize authentication\nnpx @knowcode/doc-builder auth:init\n\n# Add your site to database  \nnpx @knowcode/doc-builder auth:add-site --domain docs.example.com --name \"My Docs\"\n\n# Grant user access\nnpx @knowcode/doc-builder auth:grant --email user@example.com --site-id xxx\n```\n\nSee the [Supabase Authentication Guide](docs/guides/supabase-auth-setup-guide.md) for complete setup instructions.\n\n## 📋 Commands Overview\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🏗️ Core Commands\n| Command | Purpose |\n|---------|---------|\n| `build` | Generate static HTML |\n| `deploy` | Deploy to Vercel |\n| `init` | Initialize project |\n\n### ⚙️ Config Commands\n| Command | Purpose |\n|---------|---------|\n| `set-production-url` | Set custom URL |\n| `reset-vercel` | Clear settings |\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🔍 SEO Commands\n| Command | Purpose |\n|---------|---------|\n| `seo-check` | Analyze SEO |\n| `setup-seo` | Configure SEO |\n| `google-verify` | Add verification |\n\n### 📚 Documentation\nAll commands support `--help` for detailed options and examples.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### 📌 Command Details\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🏗️ build\u003c/b\u003e - Generate static HTML files\u003c/summary\u003e\n\n```bash\ndoc-builder build [options]\n\nOptions:\n  -c, --config \u003cpath\u003e  Path to config file (default: \"doc-builder.config.js\")\n  -i, --input \u003cdir\u003e    Input directory (default: docs)\n  -o, --output \u003cdir\u003e   Output directory (default: html)\n  --preset \u003cpreset\u003e    Use a preset configuration\n  --no-changelog      Disable changelog generation\n\nExamples:\n  doc-builder build                          # Build with defaults\n  doc-builder build --input docs --output dist\n  doc-builder build --preset notion-inspired\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e☁️ deploy\u003c/b\u003e - Deploy to Vercel\u003c/summary\u003e\n\n```bash\ndoc-builder deploy [options]\n\nOptions:\n  -c, --config \u003cpath\u003e     Path to config file\n  --no-prod              Deploy as preview\n  --force                Force without confirmation\n  --production-url \u003curl\u003e Override production URL\n\nExamples:\n  doc-builder deploy                    # Deploy to production\n  doc-builder deploy --no-prod          # Deploy as preview\n  doc-builder deploy --production-url my-docs.vercel.app\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔍 seo-check\u003c/b\u003e - Analyze SEO optimization\u003c/summary\u003e\n\n```bash\ndoc-builder seo-check [file]\n\nAnalyzes:\n  • Title length (50-60 chars)\n  • Meta descriptions (140-160 chars)\n  • Keywords usage\n  • Front matter SEO fields\n  • Content quality signals\n\nExamples:\n  doc-builder seo-check              # Check all pages\n  doc-builder seo-check docs/guide.md # Check specific page\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e✅ google-verify\u003c/b\u003e - Add Google verification\u003c/summary\u003e\n\n```bash\ndoc-builder google-verify \u003ccode\u003e\n\nExamples:\n  doc-builder google-verify YOUR_VERIFICATION_CODE\n  doc-builder google-verify FtzcDTf5BQ9K5EfnGazQkgU2U4FiN3ITzM7gHwqUAqQ\n```\n\u003c/details\u003e\n\n\n## Project Structure\n\nYour project should follow this structure:\n\n```\nmy-project/\n├── docs/              # Markdown files\n│   ├── README.md\n│   ├── guide/\n│   └── api/\n├── doc-builder.config.js  # Configuration (optional)\n└── package.json\n```\n\n## Working with Claude Code\n\nMany users leverage Claude Code to create and maintain their documentation. Claude Code is particularly effective at:\n\n### Generating Documentation\nClaude Code can analyze your codebase and automatically generate comprehensive documentation:\n- API documentation from code comments and function signatures\n- User guides based on your application structure\n- Installation and setup instructions\n- Troubleshooting guides\n\n### Documentation Conventions\nWhen using Claude Code to generate documentation, it typically follows these patterns:\n- Creates properly structured markdown files with hierarchical headings\n- Includes code examples with syntax highlighting\n- Generates Mermaid diagrams for visual representations\n- Follows consistent naming conventions (e.g., `component-guide.md`, `api-reference.md`)\n- Adds metadata headers for document tracking\n\n### Example Claude Code Workflow\n1. **Initial Documentation Generation**\n   ```\n   \"Create comprehensive API documentation for this project\"\n   ```\n   Claude Code will scan your codebase and generate appropriate markdown files in your `docs/` directory.\n\n2. **Updating Documentation**\n   ```\n   \"Update the API documentation to reflect the new authentication methods\"\n   ```\n   Claude Code will modify existing files while preserving structure and formatting.\n\n3. **Adding Visual Documentation**\n   ```\n   \"Add a Mermaid diagram showing the application architecture\"\n   ```\n   Claude Code will create diagrams that are automatically rendered by doc-builder.\n\n### Best Practices with Claude Code\n- **Structured Requests**: Be specific about what documentation you need\n- **Iterative Updates**: Claude Code can update existing docs without starting from scratch\n- **Review Generated Content**: Always review AI-generated documentation for accuracy\n- **Maintain CLAUDE.md**: Keep project-specific instructions in a CLAUDE.md file for consistent documentation style\n\n## 🔧 Troubleshooting\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🐛 Common Issues\n\n**\"Command not found\" error**\n```bash\n# Check Node.js version\nnode --version  # Need 14+\n\n# Use full package name\nnpx @knowcode/doc-builder@latest\n```\n\n**\"No markdown files found\"**\n- Docs in `docs/` folder?\n- Files have `.md` extension?\n- Try: `--input ./my-docs`\n\n**Vercel deployment fails**\n```bash\n# Reset Vercel settings\nnpx @knowcode/doc-builder@latest reset-vercel\n\n# Install Vercel CLI\nnpm install -g vercel\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### ⚠️ NPX Cache Issues\n\n**Symptoms:**\n- Old version runs despite update\n- New features unavailable\n- Wrong version number shown\n\n**Solutions:**\n```bash\n# Clear NPX cache\nnpx clear-npx-cache\n\n# Force latest version\nnpx @knowcode/doc-builder@latest\n\n# Use specific version\nnpx @knowcode/doc-builder@1.5.14\n```\n\n**Prevention:**\n- Always use `@latest` for newest\n- Clear cache when testing\n- Use `npm install` for projects\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### 🪟 Windows Setup\n\nHaving issues on Windows? Check our comprehensive [Windows Setup Guide](docs/guides/windows-setup-guide.md) that covers:\n- PowerShell execution policy setup\n- Node.js and npm installation\n- Git for Windows configuration\n- Complete troubleshooting steps\n\n### 🔗 Production URL Issues\n\n\u003cdetails\u003e\n\u003csummary\u003eWrong URL displayed after deployment?\u003c/summary\u003e\n\n**Option 1: Config File**\n```javascript\n// doc-builder.config.js\nmodule.exports = {\n  productionUrl: 'https://my-docs.vercel.app'\n};\n```\n\n**Option 2: CLI Command**\n```bash\nnpx @knowcode/doc-builder@latest set-production-url my-docs.vercel.app\n```\n\n**Option 3: Deploy Override**\n```bash\nnpx @knowcode/doc-builder@latest deploy --production-url my-docs.vercel.app\n```\n\u003c/details\u003e\n\n## 🔗 Integration Options\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### Development Integration\n\n**NPM Link (Local Dev)**\n\n```bash\n# In doc-builder directory\nnpm link\n\n# In your project\nnpm link @knowcode/doc-builder\n```\n\n**File Reference (Monorepos)**\n\n```json\n{\n  \"devDependencies\": {\n    \"@knowcode/doc-builder\": \n      \"file:../path/to/doc-builder\"\n  }\n}\n```\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### Production Integration\n\n**NPM Registry (Recommended)**\n\n```json\n{\n  \"devDependencies\": {\n    \"@knowcode/doc-builder\": \"^1.5.14\"\n  }\n}\n```\n\n**Git Repository (Private)**\n\n```json\n{\n  \"devDependencies\": {\n    \"@knowcode/doc-builder\": \n      \"git+https://github.com/knowcode/doc-builder.git\"\n  }\n}\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## 📄 License\n\nMIT License - See [LICENSE](LICENSE) file for details\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### Quick Links\n\n[**NPM Package**](https://www.npmjs.com/package/@knowcode/doc-builder) | [**Live Demo**](https://doc-builder-delta.vercel.app) | [**Report Issues**](https://github.com/wapdat/doc-builder/issues) | [**Changelog**](CHANGELOG.md)\n\nMade with ❤️ by the @knowcode team\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwapdat%2Fdoc-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwapdat%2Fdoc-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwapdat%2Fdoc-builder/lists"}