@knowcode/doc-builder

Beautiful documentation with the least effort possible. A zero-configuration documentation builder that transforms markdown files into stunning static sites.

🔗 View Live Example | 📦 NPM Package | 📚 Documentation

Quick Start

npx @knowcode/doc-builder@latest deploy

---

🎯 Core Value Proposition

Problem	Solution
Complex documentation setup	Zero configuration needed
Deployment headaches	One-command Vercel deployment
Expensive hosting	Free tier with Vercel
Ugly default themes	Beautiful Notion-inspired design
Manual navigation	Auto-generated from folder structure

What It Does

@knowcode/doc-builder transforms your markdown files into beautiful, static documentation websites. It:

• Scans your markdown files and automatically generates navigation
• Converts markdown to HTML with syntax highlighting and diagram support
• Enhances images with clickable modals for full-screen viewing
• Styles everything with a clean, Notion-inspired theme
• Deploys to Vercel with a single command - leveraging their generous free tier
• Provides optional features like authentication, dark mode, and changelog generation, SEO

Perfect for project documentation, API references, knowledge bases, or any content written in markdown.

Why Vercel?

We chose Vercel as our deployment platform because of their generous free tier that includes:

• Unlimited personal projects
• Automatic HTTPS certificates
• Global CDN for fast loading worldwide
• Custom domains support
• Automatic deployments from Git
• No credit card required

This aligns perfectly with our mission: beautiful documentation should be accessible to everyone, without worrying about hosting costs or complex server management.

✨ Features

🛠️ Core Features 🚀 Zero Configuration - Works out of the box 📝 Markdown Support - Full GitHub Flavored Markdown 🎨 Beautiful Theme - Notion-inspired design 📦 Self-Contained - No setup required 🤖 Claude Code Ready - AI-optimized workflows

🎯 Advanced Features 🔍 SEO Optimized - Meta tags & structured data 🔐 Optional Auth - Supabase authentication (opt-in) 📊 Mermaid Diagrams - Enhanced styling with rounded corners & Notion-inspired themes 🖼️ Image Modals - Click any image for full-screen view 🌙 Dark Mode - Automatic theme switching ☁️ Vercel Deploy - One-command deployment ✅ Google Verification - Search Console ready 📎 Attachment Support - Excel, PDF & more deploy with docs 🌐 HTML Embedding - Include interactive HTML pages via iframes

📋 Prerequisites

System Requirements Node.js version 14.0 or higher is required to run doc-builder. To check if you have Node.js installed: node --version If you see a version number (e.g., v18.17.0), you're ready to go!

Installing Node.js & npm 🍎 macOS Recommended: Download from nodejs.org Alternative: Using Homebrew brew install node 🪟 Windows Recommended: Download from nodejs.org Alternative: Using Chocolatey choco install nodejs

Quick Installation Links

Platform	Official Installer	Package Manager
macOS	Download .pkg	brew install node
Windows	Download .msi	choco install nodejs
Linux	Download options	apt install nodejs or yum install nodejs

💡 Note: npm (Node Package Manager) is included with Node.js installation automatically.

🚀 Getting Started

Option 1: NPX (No Installation) # Deploy to Vercel npx @knowcode/doc-builder@latest deploy # Build static HTML npx @knowcode/doc-builder@latest build # Show help npx @knowcode/doc-builder@latest Perfect for trying it out!

Option 2: NPM Install # Install as dev dependency npm install --save-dev @knowcode/doc-builder@latest # Use shorter commands doc-builder deploy doc-builder build doc-builder --help Better for regular use & offline access

First-Time Vercel Deployment

The deployment process is now simpler than ever:

1. Run npx @knowcode/doc-builder@latest deploy
2. Answer a few simple questions (project name, etc.)
3. Vercel CLI automatically detects and configures everything
4. Get your live URL in seconds!

Making Your Docs Public

After deployment, if you want public access:

1. Go to Vercel Dashboard
2. Click your project → Settings → Deployment Protection
3. Set Vercel Authentication to Disabled
4. Save changes

See the First-Time Setup Guide for a complete walkthrough.

Configuration (optional - can be managed with CLI)

Create doc-builder.config.js in your project root:

module.exports = {
  // Directories
  docsDir: 'docs',
  outputDir: 'html',
  
  // Site info
  siteName: '@knowcode/doc-builder',
  siteDescription: 'Transform markdown into beautiful documentation',
  favicon: '✨',  // Can be emoji or path to image file
  
  // Production URL (optional)
  productionUrl: 'https://my-docs.vercel.app',  // Custom URL to display after deployment
  
  // Features
  features: {
    authentication: 'supabase',  // or false for no auth
    changelog: true,
    mermaid: true,
    mermaidEnhanced: true,      // Enhanced styling with rounded corners
    darkMode: true,
    attachments: true           // Copy PDFs, Excel files, etc. (default: true)
  },
  
  // Supabase Authentication (v1.8.2+ has built-in defaults)
  auth: {
    supabaseUrl: process.env.SUPABASE_URL,       // Optional
    supabaseAnonKey: process.env.SUPABASE_ANON_KEY  // Optional
    // Domain-based auth - no siteId needed!
  }
};

🔐 Supabase Authentication

Secure your documentation with enterprise-grade authentication powered by Supabase. Built-in credentials mean zero configuration required!

✨ Authentication Features

Feature	Description
🔐 Enterprise Security	JWT tokens, bcrypt hashing, Row Level Security
🏗️ Zero Configuration	Built-in Supabase credentials - just enable and go
🌐 Domain-based Access	No site registration needed - uses your domain automatically
📁 Private Directory Support	/private/ folders automatically protected
👥 Multi-user Management	Unlimited users with fine-grained access control
🔄 Session Management	Auto-refresh tokens, persistent sessions
🎨 Beautiful Login Pages	Auto-generated login/logout pages with your theme

🚀 Quick Setup

Option 1: Private Directory (Recommended)

# Create private folder - authentication automatically enabled!
mkdir docs/private
echo "# Secret Documentation" > docs/private/admin.md
npx @knowcode/doc-builder deploy

Option 2: Global Authentication

// doc-builder.config.js
module.exports = {
  features: {
    authentication: 'supabase'  // Protect entire site
  }
};

👥 User Management

# Grant user access to your domain (SQL in Supabase dashboard)
INSERT INTO docbuilder_access (user_id, domain)
VALUES (
    (SELECT id FROM auth.users WHERE email = 'user@example.com'),
    'your-docs-domain.vercel.app'
);

🔧 Authentication Modes

• 🌍 Global Auth: Entire site requires login (authentication: 'supabase')
• 📁 Private Directory: Only /private/ folders protected (automatic)
• 🔄 Hybrid: Public docs + private sections (most flexible)

📚 Complete Guide

See the Complete Supabase Authentication Guide for:

• Detailed setup instructions
• Database schema setup
• User management workflows
• Security best practices
• Troubleshooting guide

📎 Attachment Support

doc-builder automatically copies attachment files (Excel, PDF, images, etc.) to your deployment:

• Enabled by default - No configuration needed
• Preserves directory structure - Files maintain their relative paths
• Supported file types:
  • Documents: .pdf, .doc, .docx, .xls, .xlsx, .csv, .ppt, .pptx
  • Images: .png, .jpg, .jpeg, .gif, .svg, .webp
  • Archives: .zip, .tar, .gz, .7z, .rar
  • Data files: .json, .xml, .yaml, .yml
  • And more...

Example: If you have docs/data/report.xlsx, it will be copied to html/data/report.xlsx and links like [Download Report](data/report.xlsx) will work perfectly.

To disable attachment copying, use the --no-attachments flag with build or deploy commands.

🛡️ File Safety & Non-Printable Character Handling

doc-builder v1.9.26+ automatically handles files with non-printable characters in their names to prevent build failures:

• Automatic Detection: Files with non-printable ASCII characters (0x00-0x1F, 0x7F-0x9F) are automatically detected
• Safe Processing: Problematic files are skipped during scanning with a warning message
• Clear Feedback: You'll see messages like: ⚠️ Skipping file with non-printable characters: [sanitized name]
• Prevents Errors: Eliminates YAML parsing errors and build failures caused by malformed filenames

Common scenarios this fixes:

• Files copied from certain operating systems with special characters
• Documents exported from applications that add invisible control characters
• Files with corruption in their metadata
• Cross-platform compatibility issues

This ensures your documentation builds successfully even when your source directory contains files with problematic names.

📋 Commands Overview

🏗️ Core Commands Command Purpose build Generate static HTML deploy Deploy to Vercel init Initialize project ⚙️ Config Commands Command Purpose set-production-url Set custom URL reset-vercel Clear settings

🔍 SEO Commands Command Purpose seo-check Analyze SEO setup-seo Configure SEO google-verify Add verification 📚 Documentation All commands support --help for detailed options and examples.

📌 Command Details

🏗️ build - Generate static HTML files

doc-builder build [options]

Options:
  -c, --config <path>  Path to config file (default: "doc-builder.config.js")
  -i, --input <dir>    Input directory (default: docs)
  -o, --output <dir>   Output directory (default: html)
  --preset <preset>    Use a preset configuration
  --no-changelog      Disable changelog generation
  --no-attachments    Disable copying of attachment files

Examples:
  doc-builder build                          # Build with defaults
  doc-builder build --input docs --output dist
  doc-builder build --preset notion-inspired
  doc-builder build --no-attachments         # Build without copying PDFs, Excel files, etc.

☁️ deploy - Deploy to Vercel

doc-builder deploy [options]

Options:
  -c, --config <path>     Path to config file
  --no-prod              Deploy as preview
  --force                Force without confirmation
  --production-url <url> Override production URL
  --no-attachments       Disable copying of attachment files

Examples:
  doc-builder deploy                    # Deploy to production
  doc-builder deploy --no-prod          # Deploy as preview
  doc-builder deploy --production-url my-docs.vercel.app
  doc-builder deploy --no-attachments  # Deploy without attachment files

🔍 seo-check - Analyze SEO optimization

doc-builder seo-check [file]

Analyzes:
  • Title length (50-60 chars)
  • Meta descriptions (140-160 chars)
  • Keywords usage
  • Front matter SEO fields
  • Content quality signals

Examples:
  doc-builder seo-check              # Check all pages
  doc-builder seo-check docs/guide.md # Check specific page

✅ google-verify - Add Google verification

doc-builder google-verify <code>

Examples:
  doc-builder google-verify YOUR_VERIFICATION_CODE
  doc-builder google-verify FtzcDTf5BQ9K5EfnGazQkgU2U4FiN3ITzM7gHwqUAqQ

Project Structure

Your project should follow this structure:

my-project/
├── docs/              # Markdown files
│   ├── README.md
│   ├── guide/
│   └── api/
├── doc-builder.config.js  # Configuration (optional)
└── package.json

File and Folder Naming Conventions

• Hidden files: Files and folders starting with . (dot) are ignored
• Private files: Files and folders starting with _ (underscore) are excluded from navigation
• Authentication: Use a private/ folder for content requiring authentication

Examples:

docs/
├── README.md           # ✅ Included in navigation
├── guide.md            # ✅ Included
├── _draft.md           # ❌ Excluded (starts with underscore)
├── .hidden.md          # ❌ Excluded (starts with dot)
├── _internal/          # ❌ Entire folder excluded
│   └── notes.md        # ❌ Not visible in navigation
├── private/            # 🔐 Requires authentication
│   └── admin.md        # 🔐 Only visible to authenticated users
└── public/             # ✅ Normal folder
    └── faq.md          # ✅ Included

This is useful for:

• Keeping draft documents in your docs folder without publishing them
• Storing internal notes or templates
• Maintaining work-in-progress files alongside published documentation

Working with Claude Code

Many users leverage Claude Code to create and maintain their documentation. Claude Code is particularly effective at:

Generating Documentation

Claude Code can analyze your codebase and automatically generate comprehensive documentation:

• API documentation from code comments and function signatures
• User guides based on your application structure
• Installation and setup instructions
• Troubleshooting guides

Documentation Conventions

When using Claude Code to generate documentation, it typically follows these patterns:

• Creates properly structured markdown files with hierarchical headings
• Includes code examples with syntax highlighting
• Generates Mermaid diagrams for visual representations
• Follows consistent naming conventions (e.g., component-guide.md, api-reference.md)
• Adds metadata headers for document tracking

Example Claude Code Workflow

1. Initial Documentation Generation

   "Create comprehensive API documentation for this project"
   

   Claude Code will scan your codebase and generate appropriate markdown files in your docs/ directory.

2. Updating Documentation

   "Update the API documentation to reflect the new authentication methods"
   

   Claude Code will modify existing files while preserving structure and formatting.

3. Adding Visual Documentation

   "Add a Mermaid diagram showing the application architecture"
   

   Claude Code will create diagrams that are automatically rendered by doc-builder.

Best Practices with Claude Code

• Structured Requests: Be specific about what documentation you need
• Iterative Updates: Claude Code can update existing docs without starting from scratch
• Review Generated Content: Always review AI-generated documentation for accuracy
• Maintain CLAUDE.md: Keep project-specific instructions in a CLAUDE.md file for consistent documentation style

🔧 Troubleshooting

🐛 Common Issues "Command not found" error # Check Node.js version node --version # Need 14+ # Use full package name npx @knowcode/doc-builder@latest "No markdown files found" Docs in docs/ folder? Files have .md extension? Try: --input ./my-docs Vercel deployment fails # Reset Vercel settings npx @knowcode/doc-builder@latest reset-vercel # Install Vercel CLI npm install -g vercel

⚠️ NPX Cache Issues Symptoms: Old version runs despite update New features unavailable Wrong version number shown Solutions: # Clear NPX cache npx clear-npx-cache # Force latest version npx @knowcode/doc-builder@latest # Use specific version npx @knowcode/doc-builder@1.5.14 Prevention: Always use @latest for newest Clear cache when testing Use npm install for projects

🪟 Windows Setup

Having issues on Windows? Check our comprehensive Windows Setup Guide that covers:

• PowerShell execution policy setup
• Node.js and npm installation
• Git for Windows configuration
• Complete troubleshooting steps

🔗 Production URL Issues

Wrong URL displayed after deployment?

Option 1: Config File

// doc-builder.config.js
module.exports = {
  productionUrl: 'https://my-docs.vercel.app'
};

Option 2: CLI Command

npx @knowcode/doc-builder@latest set-production-url my-docs.vercel.app

Option 3: Deploy Override

npx @knowcode/doc-builder@latest deploy --production-url my-docs.vercel.app

🔗 Integration Options

Development Integration NPM Link (Local Dev) # In doc-builder directory npm link # In your project npm link @knowcode/doc-builder File Reference (Monorepos) { "devDependencies": { "@knowcode/doc-builder": "file:../path/to/doc-builder" } }

Production Integration NPM Registry (Recommended) { "devDependencies": { "@knowcode/doc-builder": "^1.5.14" } } Git Repository (Private) { "devDependencies": { "@knowcode/doc-builder": "git+https://github.com/knowcode/doc-builder.git" } }

📄 License

MIT License - See LICENSE file for details

---

Quick Links

NPM Package | Live Demo | Report Issues | Changelog

Made with ❤️ by the @knowcode team