@knowcode/doc-builder

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

npx @knowcode/doc-builder@latest deploy

🎯 Core Value Proposition

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

📋 Prerequisites

node --version

Quick Installation Links

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

🚀 Getting Started

# 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

# Install as dev dependency
npm install --save-dev @knowcode/doc-builder@latest

# Use shorter commands
doc-builder deploy
doc-builder build
doc-builder --help

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

🚀 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

📌 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

# Check Node.js version
node --version  # Need 14+

# Use full package name
npx @knowcode/doc-builder@latest

# Reset Vercel settings
npx @knowcode/doc-builder@latest reset-vercel

# Install Vercel CLI
npm install -g vercel

# 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

🪟 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

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

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

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

🔗 Integration Options

# In doc-builder directory
npm link

# In your project
npm link @knowcode/doc-builder

{
  "devDependencies": {
    "@knowcode/doc-builder": 
      "file:../path/to/doc-builder"
  }
}

{
  "devDependencies": {
    "@knowcode/doc-builder": "^1.5.14"
  }
}

{
  "devDependencies": {
    "@knowcode/doc-builder": 
      "git+https://github.com/knowcode/doc-builder.git"
  }
}

📄 License

MIT License - See LICENSE file for details