Introduction
Trellis Docs is a documentation framework built on Next.js that adds theme enhancements, a design token system, bundled plugins, and reusable components — so you can focus on writing content instead of configuring tooling.
Why Trellis Docs?
Next.js is a powerful React framework, but setting up a polished documentation site requires significant customization: building theme components, configuring search, adding image zoom, managing redirects, and aligning your design system. Trellis Docs does this work upfront so every project starts with a consistent, production-ready baseline.
- Variables in content — Define product names, versions, and terms once. Use them on every page. Rename a product? Change one file.
- Your components, your way — Drop in React components per-page or register them globally. No swizzling, no ejecting, no magic.
- Own your output — Static HTML export. Deploy to any host. No vendor lock-in, no runtime server, no SaaS subscription.
- Content audit built in — Export your entire doc inventory as a CSV — title, URL, doc type, author, draft status, last updated. The only docs framework with this built in.
- Built by a technical content manager, not a framework team — Every default reflects 30 years of documentation experience. Last-updated dates at the top, not buried. Heading anchors that copy on click. Search that works without Algolia.
What's included
| Category | What you get |
|---|---|
| Theme | Custom components with UX improvements — last-updated at page top, heading copy-to-clipboard, tab URL sync, custom admonition icons, pill-style tabs |
| Design Tokens | JSON-to-CSS pipeline that converts design-tokens.json into CSS custom properties at build time |
| Smart Search | Build-time indexing with Fuse.js for fast, client-side fuzzy search with configurable field weights |
| Image Lightbox | Click-to-zoom on any markdown image — no extra markup needed |
| Mermaid Diagrams | Built-in Mermaid rendering with pan and zoom support |
| FAQ Indexer | Auto-generates a searchable FAQ table of contents from ### headings in your FAQ pages |
| Redirects | Manages URL redirects via a JSON file — generates HTML meta-refresh pages at build time |
| Components | Reusable React components: Glossary, Feedback widget, Flipping cards, Custom search UI |
| Content Audit Export | Export your full doc inventory as a CSV — title, URL, doc type, owner, draft status, last updated. Run npm run export:sidebar at any time |
Trellis Docs vs Next.js
Trellis Docs is built on top of Next.js — it doesn't replace it. Everything Next.js provides still works. Trellis Docs adds a layer of theme customizations, bundled plugins, and developer experience improvements.
| Feature | Vanilla Next.js | Trellis Docs |
|---|---|---|
| Last-updated date | Shown at the bottom of the page | Moved to the top, below the title — gives readers immediate context about freshness |
| Heading anchors | Hover shows a # link | Hover shows a link icon with copy-to-clipboard functionality |
| Tab selection | Synced via localStorage | Synced via URL query parameters — shareable links open on the correct tab |
| Tab styling | Underline-style tabs | Pill-style tabs with accent colors |
| Admonition icons | Default emoji-based icons | Custom SVG icons for each type (note, tip, info, caution, danger) |
| Dark mode | Light mode default | Dark mode default with respectPrefersColorScheme enabled |
| Design tokens | Manual CSS variable management | JSON-to-CSS pipeline — edit one JSON file, regenerate all variables |
| Search | Requires Algolia or third-party plugin | Built-in smart search — Fuse.js client-side search with configurable weights |
| Image lightbox | Not included | Select-to-zoom on any markdown image, automatic — no markup changes |
| Mermaid diagrams | Available as a theme plugin | Pre-configured with pan and zoom support |
| FAQ indexing | Not included | Auto-generates searchable FAQ table of contents from ### headings |
| Redirects | Requires manual redirect configuration | JSON-based redirect management with HTML meta-refresh generation |
What stays the same
Trellis Docs doesn't modify these Next.js fundamentals:
- MDX content authoring — same markdown syntax, same component imports
- Routing — file-based routing in
content/docs/,content/blog/,app/ - Configuration —
config/site.tswith the same API - Deployment — same static output, deploy anywhere
- Syntax highlighting — Shiki-powered code blocks with dual light/dark themes
When to use Trellis Docs
Use Trellis Docs when:
- You want a polished docs site without spending time on theme customization
- You need built-in search that doesn't require Algolia
- Your team wants a design token system for consistent branding
- You're building internal developer documentation
Stick with vanilla Next.js when:
- You need complete control over every theme component from scratch
- You prefer to pick and choose individual plugins
- Your project has specific theme requirements that conflict with Trellis Docs defaults
Framework comparison
How Trellis Docs stacks up against the most popular docs-as-code frameworks.
| Capability | Trellis Docs | Docusaurus | Nextra | Starlight | MkDocs | GitBook |
|---|---|---|---|---|---|---|
| Static export | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ |
| MDX support | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ |
| Reusable content variables | ✓ | ✗ | ✗ | ✗ | ✗ | ✓ |
| Include / partial directives | ✓ | ✗ | ✗ | ✗ | ✓ | ✗ |
| Custom components in content | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ |
| Client-side search (no external service) | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Configurable search weights | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Tab state in URL | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Design token pipeline | ✓ | ✗ | ✗ | ◐ | ✗ | ✗ |
| Content audit CSV export | ✓ | ✗ | ✗ | ✗ | ✗ | ◐ |
| Built-in feedback widget | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| API docs (OpenAPI) | ✓ | ◐ | ✗ | ◐ | ◐ | ✗ |
| Blog support | ✓ | ✓ | ✓ | ◐ | ◐ | ✗ |
| Dark mode out of the box | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| i18n / localization | ✓ | ✓ | ◐ | ✓ | ✓ | ◐ |
| Documentation versioning | ✓ | ✓ | ✗ | ◐ | ✓ | ◐ |
| Audience role tagging | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Build-time link checking | ✓ | ✓ | ✗ | ✗ | ◐ | ✗ |
| Migration tooling | ✓ | N/A | ✗ | ✗ | ✗ | ✗ |
| CLI scaffolding | ✓ | ✓ | ◐ | ✓ | ✗ | ✗ |
| TypeScript config | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ |
| Self-hosted / deploy anywhere | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ |
| Free & open source | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ |
✓ = included ◐ = partial or plugin required ✗ = not available
Tech stack
| Layer | Technology |
|---|---|
| Framework | Next.js 15 |
| Styling | Tailwind CSS v4 |
| Components | shadcn/ui |
| MDX | next-mdx-remote v5 |
| Search | Fuse.js |
| Syntax | Shiki |
| Diagrams | Mermaid |
| Output | Static HTML |
Who is it for?
- Technical writers who want a polished docs site without front-end configuration
- Platform teams building internal developer portals
- Open-source projects that need more than a vanilla docs setup out of the box
- Anyone who wants to start writing docs, not configuring build tools
How it works
The build pipeline:
- Design tokens are defined in
design-tokens.jsonand converted to CSS custom properties. - Theme components consume those tokens through CSS variables.
- Plugins (search, FAQ index, redirects, lightbox) hook into the build lifecycle.
- Next.js compiles everything into a static site.
Who built it
Trellis Docs was created by Patricia McPhee, a technical writer with 30 years in tech. She has documented APIs, SDKs, and developer platforms at Microsoft, Amazon, Facebook/Oculus, GE Healthcare, LivePerson, Beyond Identity, and Expedia Group. Her specialties are developer documentation, docs-as-code workflows, and information architecture.
Trellis Docs exists because every docs framework she used was missing something. Docusaurus doesn't support reusable variables. Nextra has no design token system. Starlight is tied to Astro. GitBook locks you into a paid platform. Trellis Docs combines the best ideas from all of them into a single, self-hosted framework built on Next.js — the React framework most teams already know.
Next steps
- Getting Started — set up a new project
- Architecture — understand how the pieces fit together
- Migrating from Docusaurus — move an existing Docusaurus site to Trellis Docs
- Roadmap — see what's coming next