Getting Started

Folio turns a directory of Markdown and MDX files into a file-based documentation site. Routes are derived from the content directory, and the default theme provides navigation, search, syntax highlighting, and responsive layouts. The files can document any project, library, API, or product.

Requirements

You need:

• Bun, npm, pnpm, or yarn;
• a directory containing Markdown or MDX files, or an empty directory for a new documentation project;
• Tailwind CSS v4 when using the generated default theme.

The commands below use the package manager selected for your project. The engine is not tied to Bun.

Create a documentation project

Install the engine in an existing project:

$ bun add @nikala-ui/folio

Then initialize the documentation structure:

$ bunx @nikala-ui/folio init .

The initializer creates the documentation structure and installs the dependencies required by the generated theme. It merges the generated scripts and dependencies into package.json, while existing docs.config.ts and nikala.config.json files are preserved.

The generated project contains:

.
├── docs/
│   └── index.mdx
├── docs.config.ts
├── nikala.config.json
├── public/
│   └── favicon.ico
└── src/
    ├── components/ui/
    ├── hooks/
    ├── index.css
    ├── lib/
    ├── providers/
    └── themes/default/

It also configures the @/* TypeScript path alias and adds dev, build, and preview scripts when they are not already defined.

Start the development server

From the project root, run the generated development script:

$ bun run dev

The default development server is available at http://localhost:1862/.

The server watches the configured content directory and reloads routes and configuration changes during development.

Add your first page

Create an MDX file under docs/:

---
title: Installation
description: Install the dependencies for your project.
order: 1
---

# Installation

Install the package with your preferred package manager, then start the
development server.

The file path becomes the route. For example:

docs/index.mdx              -> /
docs/installation.mdx       -> /installation
docs/guides/theming.mdx     -> /guides/theming

Directories become sidebar categories automatically. Use frontmatter such as order, categoryOrder, icon, badge, toc, prev, and next to control page metadata and navigation.

Configure the site

The initializer creates docs.config.ts in the project root. A minimal configuration looks like this:

import type { DocsConfig } from "@nikala-ui/folio";

const config: DocsConfig = {
  title: "My Project Docs",
  description: "Documentation for my project.",
  contentDir: "docs",
  favicon: "/favicon.ico",
  navigation: {
    layout: "sidebar",
    navbar: [{ title: "Home", href: "/" }],
    sidebar: {
      nav: "auto",
      header: true,
      footer: false,
      headerSubtitle: "Documentation",
    },
  },
  search: {
    enabled: true,
    provider: "local",
  },
};

export default config;

The full configuration reference is available in Configuration.

Use Nikala UI with the documentation site

The default theme uses Nikala UI components. When you need additional UI components or theme capabilities, use the Nikala UI CLI from the generated project:

$ bunx @nikala-ui/cli add button

The CLI writes the selected source into the project so it can be used and customized locally.

Build and preview for production

Build the site and preview the generated production output:

$ bun run build

$ bun run preview

The build writes the documentation site to dist/. The preview command serves that production output locally. Use the production build before deploying to catch SSR, routing, and asset-path issues that may not appear in development mode.