@knowcode/doc-builder

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


---

🎯 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

📋 Prerequisites

$3

| 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

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!

$3

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:

`javascript
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!
}
};
`

$3

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)
`bash


Create private folder - authentication automatically enabled!

Option 2: Global Authentication
`javascript
// doc-builder.config.js
module.exports = {
features: {
authentication: 'supabase' // Protect entire site
}
};
`

#### 👥 User Management

`bash


Grant user access to your domain (SQL in Supabase dashboard)

- 🌍 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

$3

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 will work perfectly.

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

$3

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

$3

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
`

$3

- 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:

$3