Installation

Get DocsKit running locally in under 10 minutes. This guide covers prerequisites, local setup, the project structure you'll find inside, environment configuration, and deployment options.

Prerequisites

Before you start, make sure you have the following installed:

Node.js 18.17 or later - Next.js 14 requires Node 18+. Check your version with node -v. Install from nodejs.org or via a version manager like nvm or fnm.
A package manager - pnpm is recommended (faster installs, better monorepo support), but npm and yarn both work.

To install pnpm if you don't already have it:

npm install -g pnpm

Purchase DocsKit from the marketplace and download the zip archive. Extract it to a directory of your choosing - for example ~/projects/my-docs. The extracted folder is a self-contained Next.js project, not a monorepo.

Install dependencies

Navigate to the project root and install:

pnpm install

This installs Next.js, next-mdx-remote, Shiki, Pagefind, Tailwind CSS, and all other dependencies. Expect 30-60 seconds on a first install.

Start the development server

pnpm dev

The site is available at http://localhost:3002. The marketing homepage is at / and the docs are at /docs.

Project structure

After installation, here's what you'll find:

my-docs/
  content/
    docs/                   # All MDX source files
      getting-started/
        introduction.mdx
        installation.mdx
        quick-start.mdx
      configuration/
        options.mdx
      components/
        callout.mdx
        code-block.mdx
      api-reference/
        steps.mdx
        tabs.mdx
  src/
    app/
      globals.css           # CSS variables + Tailwind base styles
      layout.tsx            # Root layout with metadata
      page.tsx              # Marketing homepage
      docs/
        layout.tsx          # Docs shell: sidebar + TOC wrapper
        [[...slug]]/
          page.tsx          # Dynamic route for all doc pages
    components/
      docs/
        mdx/                # Callout, CodeBlock, Steps, Tabs
        Sidebar.tsx         # Left navigation sidebar
        TableOfContents.tsx # Right-side heading TOC
      marketing/            # Marketing homepage components
    config/
      nav.ts                # Sidebar navigation definition
    lib/
      mdx.ts                # MDX compilation utilities
  next.config.ts            # Next.js configuration (static export)
  tailwind.config.ts        # Tailwind configuration
  tsconfig.json
  package.json

Environment variables

DocsKit uses one environment variable for canonical URL generation:

NEXT_PUBLIC_SITE_URL=https://docs.yourproduct.com

Create a .env.local file in the project root with the above. In development, you can leave it unset - canonical URLs will fall back to a safe default. In production, set it to your actual domain so the <link rel="canonical"> tags are correct.

NEXT_PUBLIC_ prefix is required because this variable is referenced in client-side code (the canonical URL is embedded in the page HTML). Never put secrets in NEXT_PUBLIC_ variables.

Building for production

pnpm build

The build process does two things in sequence:

Next.js static export - Compiles all MDX files and generates HTML in out/.
Pagefind indexing - Crawls out/ and writes the search index to out/pagefind/.

The postbuild script in package.json runs Pagefind automatically after the Next.js build completes. You don't need to run it manually.

Search does not work in development mode (pnpm dev). The Pagefind index is only generated during pnpm build. In dev, the search bar displays a message explaining this. This is expected behavior - run pnpm build and serve out/ locally to test search.

To preview the production build locally:

pnpm build
npx serve out

Or with Python (no extra install needed):

pnpm build
cd out && python3 -m http.server 3002

Deployment

Vercel (recommended)

Push your project to a GitHub, GitLab, or Bitbucket repository. Import it in the Vercel dashboard. Vercel detects Next.js automatically and applies the correct build settings.

Set the NEXT_PUBLIC_SITE_URL environment variable in Project Settings > Environment Variables before your first production deployment.

A vercel.json is included in the project root with the correct build settings.

Netlify

Connect your repository in the Netlify dashboard. Set the build command to pnpm build and the publish directory to out. Add NEXT_PUBLIC_SITE_URL in Site Settings > Environment Variables.

Cloudflare Pages

Use the Cloudflare Pages Git integration. Set the build command to pnpm build and the build output directory to out. Node.js version can be set via the NODE_VERSION environment variable (set it to 18).

Static host (S3, GitHub Pages, etc.)

Run pnpm build locally or in CI, then upload the contents of out/ to any static file host. Because DocsKit uses trailingSlash: true in next.config.ts, each page is emitted as page-name/index.html, which works on virtually every static host without extra rewrite rules.