@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
• 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,
    darkMode: true,
    attachments: true           // Copy PDFs, Excel files, etc. (default: true)
  },
  
  // Supabase Authentication
  auth: {
    supabaseUrl: process.env.SUPABASE_URL,
    supabaseAnonKey: process.env.SUPABASE_ANON_KEY,
    siteId: process.env.DOC_SITE_ID
  }
};

🔐 Authentication Setup

For secure documentation sites, use Supabase authentication:

# Initialize authentication
npx @knowcode/doc-builder auth:init

# Add your site to database  
npx @knowcode/doc-builder auth:add-site --domain docs.example.com --name "My Docs"

# Grant user access
npx @knowcode/doc-builder auth:grant --email user@example.com --site-id xxx

See the Supabase Authentication Guide for complete setup instructions.

📎 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.

📋 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

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