Setup Methods

Choose your preferred method to set up Docs Kit:

git clone https://github.com/your-org/docs-kit.git my-docs
cd my-docs

cd path/to/my-docs

git clone https://github.com/your-username/your-docs.git
cd your-docs

Install Dependencies

Navigate to your project directory and install dependencies:

This will install all required dependencies including Next.js, Chakra UI, and content processing libraries.

Start Development Server

Launch the development server:

Your documentation site will be available at http://localhost:3000. The development server includes:

• Hot Reload: Instant updates when you edit files
• Fast Refresh: React components update without losing state
• Error Overlay: Helpful error messages in the browser

Project Structure

Understanding the project structure:

docs-kit/
├── app/                          # Next.js App Router
│   ├── layout.tsx               # Root layout with providers
│   ├── page.tsx                 # Home page (redirects)
│   ├── global.css               # Global styles
│   └── [...slug]/               # Dynamic catch-all routes
│       ├── layout.tsx           # Docs layout
│       └── page.tsx             # Page renderer
│
├── components/                   # React components
│   ├── docs-layout.tsx          # Main layout wrapper
│   ├── mdx-page.tsx             # MDX renderer
│   ├── api-page/                # OpenAPI components
│   ├── navigation/              # Nav, sidebar, search, TOC
│   ├── mdx/                     # MDX components
│   ├── openapi/                 # Interactive API docs
│   ├── page/                    # Page components
│   └── ui/                      # UI utilities
│
├── content/                      # Content files (MDX)
│   ├── docs/                    # Documentation pages
│   ├── api-reference/           # API documentation
│   └── changelog/               # Changelog entries
│
├── lib/                         # Utility functions
│   ├── docs.ts                  # Content loading
│   ├── routes.ts                # Navigation routing
│   ├── openapi.ts               # OpenAPI utilities
│   ├── search.ts                # Search functionality
│   └── code-generator.ts        # Code examples
│
├── config/
│   └── docs.config.ts         # Site configuration
│
├── public/                      # Static assets
│   ├── logo/                    # Logo files
│   └── static/
│       └── openapi.json         # OpenAPI specification
│
├── types/                       # TypeScript types
├── velite.config.ts             # Content processing config
├── next.config.mjs              # Next.js configuration
├── tsconfig.json                # TypeScript config
└── package.json                 # Dependencies

Configuration

Before you start, configure your site in config/docs.config.ts:

{
  "name": "Your Documentation",
  "description": "Your site description",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "colorPalette": "teal"
}

Build for Production

When you're ready to deploy, create a production build:

bun run build

This command:

1. Compiles content from MDX to JSON
2. Generates search index
3. Builds Next.js application
4. Optimizes assets and images
5. Creates static pages where possible

The output is placed in the .next directory.

Test Production Build

Preview the production build locally:

bun run start

This starts a production server on http://localhost:3000 to verify everything works correctly.

Environment Variables

Create a .env.local file for environment-specific configuration:

# Site URL (used for canonical URLs and SEO)
NEXT_PUBLIC_SITE_URL=https://docs.yoursite.com

# Optional: Analytics
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Deployment

Deploy your documentation site to your preferred platform:

Vercel (Recommended)

The easiest deployment option:

# Install Vercel CLI
bun add -g vercel

# Deploy
vercel

Netlify

1. Connect your Git repository
2. Set build command: bun run build
3. Set publish directory: .next
4. Deploy

Other Platforms

Docs Kit works on any platform that supports Next.js, including:

• AWS Amplify
• Azure Static Web Apps
• DigitalOcean App Platform
• Railway
• Render

Troubleshooting

Port Already in Use

If port 3000 is taken, specify a different port:

bun dev -p 3001

Module Not Found Errors

Clear cache and reinstall:

rm -rf node_modules .next
bun install

Build Failures

Check that all content files have valid frontmatter:

---
title: "Page Title"
description: "Page description"
published: true
---

Next Steps