Getting Started

Welcome to Trellis Docs — an opinionated docs framework built on Next.js with custom theme enhancements, smart search, and a design token system.

Prerequisites

Before getting started, make sure you have the following installed:

Node.js 18+ — download here
npm, yarn, or pnpm — npm comes bundled with Node.js
Git — download here

You can verify your setup by running:

node --version   # Should print v18.x or higher
npm --version    # Should print 9.x or higher
git --version

What's included

Category	Highlights	Learn More
Theme	Last-updated at top, heading copy-to-clipboard, pill-style tabs, custom admonition icons	Theme Overview
Design Tokens	JSON-to-CSS pipeline for centralized brand management	Design Tokens
Plugins	Smart search, FAQ indexer, redirects, image lightbox, Mermaid pan/zoom	Plugins Overview
Components	Glossary, feedback widget, flipping cards, search UI	Components

New to Trellis Docs? Read What is Trellis Docs? for the full picture, or see the feature comparison with vanilla Next.js.

Quick start

Scaffold a new project with a single command:

npx create-trellis-docs my-docs
cd my-docs
npm run dev

The scaffolder prompts you for a site title, tagline, URL, and optional GitHub repository URL.

Tip

The dev server runs on port 3000 by default. Visit http://localhost:3000 to see your docs.

Platform note

Tailwind CSS v4 relies on platform-specific native binaries (via lightningcss). The scaffolder detects your OS automatically, but if you run npm install manually and your .npmrc overrides the os setting, npm might skip the correct binaries. If you see an error like Cannot find module '../lightningcss.<platform>.node', reinstall with your actual platform:

# macOS
npm install --os=darwin

# Windows
npm install --os=win32

# Linux
npm install --os=linux

Project structure

my-docs/
├── app/
│   ├── (docs)/            # Docs layout (navbar, sidebar, footer)
│   ├── blog/              # Blog pages
│   ├── release-notes/     # Release notes pages
│   ├── layout.tsx         # Root layout (providers, fonts)
│   ├── page.tsx           # Landing page
│   ├── globals.css        # Global CSS + dark/light mode tokens
│   └── tokens.css         # Generated design token CSS
├── components/
│   ├── blog/              # Blog sidebar
│   ├── brand/             # Logo components (replace with your own)
│   ├── custom/            # Reusable components (glossary, feedback, etc.)
│   └── docs/              # Layout & MDX components
├── config/
│   ├── navigation.ts      # Navbar and footer links
│   ├── sidebar.ts         # Sidebar navigation structure
│   ├── site.ts            # Site title, logo, search, i18n, versioning
│   └── variables.ts       # Reusable content variables
├── content/
│   ├── docs/              # Documentation content (MDX files)
│   ├── blog/              # Blog posts
│   └── release-notes/     # Version release notes
├── data/                  # Static data files (glossary, etc.)
├── lib/                   # Content loading, routing, utilities
├── public/img/            # Static assets (images, logos, favicon)
├── scripts/               # Build scripts (tokens, search, FAQ, versioning)
├── design-tokens.json     # Design token definitions
├── redirects.json         # URL redirect mappings
└── package.json

Next steps