@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 = '[email protected]'),
    '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

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.

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

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

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/[email protected]

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

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