Quick Start

This guide uses the Next.js App Router and mounts documentation at /docs. For an existing Next.js project, start with package installation and keep your home page and application routes.

1. Prepare the project

Use Node.js 22.12 or later, Next.js 16.3.6+ (16.x), and React / React DOM 19.2.8+ (19.x).

If you need a new project, create one with TypeScript and the App Router:

pnpm create next-app my-docs
cd my-docs

Install Code Atlas:

pnpm add @code-altas/ui@beta

The package includes JavaScript, types, and compiled CSS. Tailwind is not required for the built-in interface. Examples use app/; if you use src/app/, put route files there and keep other files in the locations shown.

2. Configure the site and first article

Create this file beside the application's package.json:

import { defineConfig } from "@code-altas/ui/config"

export default defineConfig({
  title: "My Documentation",
  description: "Guides for my project",
  logo: "/logo.svg",
  docs: {
    categories: [
      {
        name: "Guides",
        icon: "lucide:book-open",
        slug: "index",
        docs: [{ name: "Introduction", slug: "index" }],
      },
    ],
  },
})

Save your logo as public/logo.svg, then create the article:

---
title: Welcome
description: My first documentation page.
---

## Start reading

Write prose in Markdown and add components with MDX.

Both index segments remain in the file path and are omitted from the public URL, giving this article the /docs address. Each new article needs both a content file and a registered navigation entry; see File System.

3. Configure Next.js

Merge these settings into the existing configuration, keeping your other options:

import type { NextConfig } from "next"

const nextConfig: NextConfig = {
  serverExternalPackages: ["c12", "jiti"],
}

export default nextConfig

4. Add the root layout and document route

The root layout supplies html, body, and global styles. In an existing layout, merge the stylesheet import and suppressHydrationWarning, preserving your providers and other settings:

import "@code-altas/ui/styles.css"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>{children}</body>
    </html>
  )
}

DocsLayout loads site configuration and provides navigation, the theme, header, and footer:

import { DocsLayout } from "@code-altas/ui"

export default function Layout({ children }: { children: React.ReactNode }) {
  return <DocsLayout>{children}</DocsLayout>
}

An optional catch-all route handles both /docs and individual article addresses:

import { DocsPage, type DocsPageProps } from "@code-altas/ui"

export const runtime = "nodejs"
export const dynamic = "force-dynamic"

export default function Page({ params }: DocsPageProps) {
  return <DocsPage params={params} />
}

Keep pages and layouts as Server Components without "use client". params is a Promise that DocsPage reads for you.

5. Start and verify

pnpm dev

Visit http://localhost:3000/docs. You should see the Welcome title, article body, and sidebar navigation. Your Next.js home page still controls /.

For a 404, check that the configuration, content file, and route all exist and that commands run from the app root. Do not keep app/docs/page.tsx alongside this optional catch-all route, because both would serve /docs.

Next steps

• Configure branding, header, and footer with Site Configuration.
• Add categories, groups, and articles with Navigation.
• Write content with MD and MDX.
• Enable full-text search with Search.
• Before going live, configure Build and Deployment and Page Metadata.