Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/wapdat/doc-builder

Transform markdown into beautiful documentation sites with one-command Vercel deployment
https://github.com/wapdat/doc-builder

ai developer-tools markdown nodejs notion npm-packages static-site-generator vercel

Last synced: 5 months ago
JSON representation

Transform markdown into beautiful documentation sites with one-command Vercel deployment

Awesome Lists containing this project

README 

          
# @knowcode/doc-builder



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



[![npm version](https://img.shields.io/npm/v/@knowcode/doc-builder)](https://www.npmjs.com/package/@knowcode/doc-builder)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![GitHub stars](https://img.shields.io/github/stars/wapdat/doc-builder)](https://github.com/wapdat/doc-builder/stargazers)

[![GitHub issues](https://img.shields.io/github/issues/wapdat/doc-builder)](https://github.com/wapdat/doc-builder/issues)






🔗 **[View Live Example](https://doc-builder-delta.vercel.app)** | 📦 **[NPM Package](https://www.npmjs.com/package/@knowcode/doc-builder)** | 📚 **[Documentation](https://doc-builder-delta.vercel.app)**



### Quick Start

```bash

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

- **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** - Built-in diagram support

- 🌙 **Dark Mode** - Automatic theme switching

- ☁️ **Vercel Deploy** - One-command deployment

- ✅ **Google Verification** - Search Console ready



## 📋 Prerequisites



### System Requirements



**Node.js** version 14.0 or higher is required to run doc-builder.



To check if you have Node.js installed:

```bash

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](https://nodejs.org/)

- **Alternative**: Using Homebrew

  ```bash

  brew install node

  ```



**🪟 Windows**

- **Recommended**: [Download from nodejs.org](https://nodejs.org/)

- **Alternative**: Using Chocolatey

  ```bash

  choco install nodejs

  ```



### Quick Installation Links



| Platform | Official Installer | Package Manager |

|----------|-------------------|-----------------|

| **macOS** | [Download .pkg](https://nodejs.org/en/download/) | `brew install node` |

| **Windows** | [Download .msi](https://nodejs.org/en/download/) | `choco install nodejs` |

| **Linux** | [Download options](https://nodejs.org/en/download/) | `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)

```bash

# 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

```bash

# 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](https://vercel.com/dashboard)

2. Click your project → Settings → Deployment Protection

3. Set **Vercel Authentication** to **Disabled**

4. Save changes



See the [First-Time Setup Guide](docs/vercel-first-time-setup-guide.md) 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,

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



```bash

# 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](docs/guides/supabase-auth-setup-guide.md) for complete setup instructions.



## 📋 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



```bash

doc-builder build [options]



Options:

  -c, --config   Path to config file (default: "doc-builder.config.js")

  -i, --input     Input directory (default: docs)

  -o, --output    Output directory (default: html)

  --preset     Use a preset configuration

  --no-changelog      Disable changelog generation



Examples:

  doc-builder build                          # Build with defaults

  doc-builder build --input docs --output dist

  doc-builder build --preset notion-inspired

```



☁️ deploy - Deploy to Vercel



```bash

doc-builder deploy [options]



Options:

  -c, --config      Path to config file

  --no-prod              Deploy as preview

  --force                Force without confirmation

  --production-url  Override production URL



Examples:

  doc-builder deploy                    # Deploy to production

  doc-builder deploy --no-prod          # Deploy as preview

  doc-builder deploy --production-url my-docs.vercel.app

```



🔍 seo-check - Analyze SEO optimization



```bash

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



```bash

doc-builder google-verify 



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



### 🐛 Common Issues



**"Command not found" error**

```bash

# 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**

```bash

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

```bash

# 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](docs/guides/windows-setup-guide.md) 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**

```javascript

// doc-builder.config.js

module.exports = {

  productionUrl: 'https://my-docs.vercel.app'

};

```



**Option 2: CLI Command**

```bash

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

```



**Option 3: Deploy Override**

```bash

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

```



## 🔗 Integration Options



### Development Integration



**NPM Link (Local Dev)**



```bash

# In doc-builder directory

npm link



# In your project

npm link @knowcode/doc-builder

```



**File Reference (Monorepos)**



```json

{

  "devDependencies": {

    "@knowcode/doc-builder": 

      "file:../path/to/doc-builder"

  }

}

```



### Production Integration



**NPM Registry (Recommended)**



```json

{

  "devDependencies": {

    "@knowcode/doc-builder": "^1.5.14"

  }

}

```



**Git Repository (Private)**



```json

{

  "devDependencies": {

    "@knowcode/doc-builder": 

      "git+https://github.com/knowcode/doc-builder.git"

  }

}

```



## 📄 License



MIT License - See [LICENSE](LICENSE) file for details



---






### Quick Links



[**NPM Package**](https://www.npmjs.com/package/@knowcode/doc-builder) | [**Live Demo**](https://doc-builder-delta.vercel.app) | [**Report Issues**](https://github.com/wapdat/doc-builder/issues) | [**Changelog**](CHANGELOG.md)



Made with ❤️ by the @knowcode team