Ardo

Getting Started

This guide will help you set up a new Ardo documentation site from scratch.

Prerequisites

Before you begin, make sure you have:

  • Node.js version 22 or higher
  • pnpm (recommended) or npm/yarn

Quick Start

The fastest way to get started is with the create-ardo CLI:

pnpm create ardo@latest my-docs
cd my-docs
pnpm install
pnpm dev

This scaffolds a complete project with configuration, example content, and a GitHub Pages deployment workflow.

Manual Installation

If you prefer to set up manually:

1. Create a new project

mkdir my-docs
cd my-docs
pnpm init

2. Install dependencies

pnpm add ardo react react-dom react-router isbot
pnpm add -D @react-router/dev typescript vite @types/react @types/react-dom

3. Create Vite configuration

Create a vite.config.ts file with your Ardo configuration:

import { defineConfig } from "vite"
import { ardo } from "ardo/vite"

export default defineConfig({
  plugins: [
    ardo({
      title: "My Documentation",
      description: "My awesome documentation site",

      themeConfig: {
        nav: [{ text: "Guide", link: "/guide/getting-started" }],
        sidebar: [
          {
            text: "Guide",
            items: [{ text: "Getting Started", link: "/guide/getting-started" }],
          },
        ],
      },
    }),
  ],
})

4. Create React Router configuration

Create a react-router.config.ts file:

import type { Config } from "@react-router/dev/config"

export default {
  ssr: false,
  prerender: true,
} satisfies Config

5. Create app files

app/root.tsx:

import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router"
import { Layout, Header, Sidebar, Footer } from "ardo/ui"
import { PressProvider } from "ardo/runtime"
import config from "virtual:ardo/config"
import sidebar from "virtual:ardo/sidebar"
import "ardo/ui/styles.css"

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  )
}

export default function Root() {
  return (
    <PressProvider config={config} sidebar={sidebar}>
      <Layout header={<Header title="My Docs" />} sidebar={<Sidebar />} footer={<Footer />}>
        <Outlet />
      </Layout>
    </PressProvider>
  )
}

app/entry.client.tsx:

import { startTransition, StrictMode } from "react"
import { hydrateRoot } from "react-dom/client"
import { HydratedRouter } from "react-router/dom"

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <HydratedRouter />
    </StrictMode>
  )
})

app/entry.server.tsx:

import type { EntryContext } from "react-router"
import { ServerRouter } from "react-router"
import { renderToReadableStream } from "react-dom/server"
import { isbot } from "isbot"

export default async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  routerContext: EntryContext
) {
  const userAgent = request.headers.get("user-agent")

  const stream = await renderToReadableStream(
    <ServerRouter context={routerContext} url={request.url} />,
    {
      onError(error: unknown) {
        console.error(error)
        responseStatusCode = 500
      },
    }
  )

  if (userAgent && isbot(userAgent)) {
    await stream.allReady
  }

  responseHeaders.set("Content-Type", "text/html")

  return new Response(stream, {
    status: responseStatusCode,
    headers: responseHeaders,
  })
}

6. Create your first document

Create app/routes/guide/getting-started.mdx:

---
title: Getting Started
---

# Getting Started

Welcome to your documentation site!

Using pnpm create ardo@latest creates all these files automatically!

Development

Start the development server:

pnpm dev

Your documentation site will be available at http://localhost:5173.

Production Build

Build your site for production:

pnpm build

The output will be in build/client/ ready for static hosting.

Preview the production build:

pnpm preview

Project Structure

A typical Ardo project looks like this:

my-docs/
├── app/
│   ├── routes/                  # Your MDX/MD content files
│   │   ├── guide/
│   │   │   └── getting-started.mdx
│   │   └── home.tsx             # Home page
│   ├── root.tsx                 # Root layout
│   ├── entry.client.tsx         # Client entry
│   └── entry.server.tsx         # Server entry
├── vite.config.ts               # Vite + Ardo configuration
├── react-router.config.ts       # React Router configuration
├── tsconfig.json
└── package.json

Next Steps

Now that you have a working documentation site: