# Ardo — React-first Static Documentation Framework

> Build beautiful documentation sites with React 19, React Router 7, and Vite.

Ardo combines the developer experience of VitePress with the power of the React ecosystem. It uses React Router 7 for file-based routing with pre-rendering, Vite for fast builds, and supports Markdown/MDX with React components.

---

## Table of Contents

1. [What is Ardo?](#what-is-ardo)
2. [Getting Started](#getting-started)
3. [Markdown Features](#markdown-features)
4. [Frontmatter](#frontmatter)
5. [UI Configuration](#ui-configuration)
6. [Custom Theme](#custom-theme)
7. [TypeDoc Integration](#typedoc-integration)
8. [Deployment](#deployment)
9. [Troubleshooting](#troubleshooting)
10. [Package Exports Reference](#package-exports-reference)

---

## What is Ardo?

Ardo is a **React-first Static Documentation Framework** built on [React Router 7](https://reactrouter.com/) and inspired by [VitePress](https://vitepress.dev) and [Starlight](https://starlight.astro.build).

### Why Ardo?

**React-First Approach** — Unlike other documentation frameworks that use their own component systems, Ardo is built entirely with React. This means:

- Use your existing React knowledge
- Import and use any React component in your docs
- Full TypeScript support out of the box
- Seamless integration with the React ecosystem

**Powered by React Router 7** — Ardo leverages React Router 7 for:

- File-based routing with automatic route generation
- Static pre-rendering for fast page loads
- Type-safe navigation
- Modern React 19 patterns

**Vite-Powered** — Built on Vite for:

- Instant dev server startup
- Lightning-fast HMR
- Optimized production builds
- Rich plugin ecosystem

### Features

- **Markdown + React** — Write in Markdown, use React components inline
- **Beautiful Default Theme** — Responsive design, dark/light mode, full-text search, TOC, syntax highlighting
- **Fully Customizable** — Theme colors, layout components, markdown processing, build pipeline

---

## Getting Started

### Prerequisites

- [Node.js](https://nodejs.org/) version 22 or higher
- [pnpm](https://pnpm.io/) (recommended) or npm/yarn

### Quick Start

The fastest way to get started:

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

### Manual Installation

#### 1. Create a new project

```bash
mkdir my-docs
cd my-docs
pnpm init
```

#### 2. Install dependencies

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

#### 3. Create Vite configuration

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

```ts
import { defineConfig } from 'vite'
import { ardo } from 'ardo/vite'

export default defineConfig({
  plugins: [
    ardo({
      title: 'My Documentation',
      description: 'My awesome documentation site',
    }),
  ],
})
```

The `ardo()` plugin handles build-time configuration only (title, description, markdown, typedoc). All UI configuration (navigation, sidebar, footer, editLink) is done via JSX props in your `root.tsx`.

#### 4. Create React Router configuration

Create a `react-router.config.ts` file:

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

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

#### 5. Create app files

Create the following files in `app/`:

- `app/root.tsx` — Root layout with Header, Sidebar, Footer
- `app/entry.client.tsx` — Client hydration entry
- `app/entry.server.tsx` — Server rendering entry using renderToReadableStream

<Tip>
Use `pnpm create ardo@latest` to scaffold all these files automatically!
</Tip>

#### 6. Create your first document

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

```markdown
---
title: Getting Started
---

# Getting Started

Welcome to your documentation site!
```

### Development

Start the development server:

```bash
pnpm dev
```

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

### Production Build

```bash
pnpm build
```

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

### Project Structure

A typical Ardo project looks like this:

```
my-docs/
├── app/
│   ├── routes/               # MDX/MD content files
│   │   ├── guide/*.mdx       # Documentation pages
│   │   └── home.tsx          # Home page
│   ├── root.tsx              # Root layout (UI configuration lives here)
│   ├── entry.client.tsx      # Client entry
│   └── entry.server.tsx      # Server entry
├── vite.config.ts            # Vite + Ardo build configuration
├── react-router.config.ts    # React Router configuration
└── package.json
```

---

## Markdown Features

Ardo supports all standard Markdown syntax plus powerful extensions.

### Basic Syntax

```markdown
# Heading 1
## Heading 2
### Heading 3

_italic_ or *italic*
**bold**
**_bold and italic_**
~~strikethrough~~

- Unordered item
  - Nested item

1. Ordered item

[Link text](https://example.com)
![Alt text](/path/to/image.png)
```

### GitHub Flavored Markdown

Tables, task lists, and autolinks are supported out of the box.

### Syntax Highlighting

Code blocks are automatically highlighted using [Shiki](https://shiki.style/). Specify the language after the opening backticks.

**Line highlighting** — Use `{lines}` syntax:

```typescript {2,4-5}
function example() {
  const highlighted = true
  const normal = false
  const alsoHighlighted = true
}
```

**Line numbers** — Use `showLineNumbers`

**Code block title** — Use `title="filename"`

### Callout Components

Highlight important information using JSX components (auto-registered in MDX, no import needed):

```markdown
<Tip>
This is a helpful tip.
</Tip>

<Warning>
Be careful!
</Warning>

<Danger>
This action cannot be undone!
</Danger>
```

### Code Groups

Display multiple code variants in tabs using `<CodeGroup labels="...">`.

### Custom Components in Markdown

Use React components directly in your markdown files by importing them.

---

## Frontmatter

Frontmatter is YAML metadata at the top of your markdown files.

### Available Options

- `title` — Page title
- `description` — Page description for SEO
- `layout` — `'doc' | 'home' | 'page'`
- `sidebar` — Whether to show sidebar
- `outline` — TOC configuration
- `editLink` — Show edit link
- `lastUpdated` — Show last updated time
- `prev / next` — Override navigation links

### Home Page Options

- `hero` — Hero section with name, text, tagline, image, actions
- `features` — Feature cards with title, icon, details, link

---

## UI Configuration

Ardo uses a JSX-first approach. All UI configuration is done via component props in your `root.tsx`, not in the Vite config.

### ArdoRoot Component

The `ArdoRoot` component is the all-in-one entry point that combines provider, layout, header, sidebar, and footer:

```tsx
import { ArdoRoot, ArdoNav, ArdoNavLink, ArdoSocialLink } from "ardo/ui"
import config from "virtual:ardo/config"
import sidebar from "virtual:ardo/sidebar"

export default function Root() {
  return (
    <ArdoRoot
      config={config}
      sidebar={sidebar}
      headerProps={{
        nav: (
          <ArdoNav>
            <ArdoNavLink to="/guide/getting-started">Guide</ArdoNavLink>
            <ArdoNavLink to="/api-reference">API</ArdoNavLink>
          </ArdoNav>
        ),
      }}
      footerProps={{
        message: "Released under the MIT License.",
      }}
      editLink={{
        pattern: "https://github.com/user/repo/edit/main/docs/:path",
        text: "Edit this page on GitHub",
      }}
      lastUpdated={{ enabled: true }}
    />
  )
}
```

### Navigation

Pass navigation as JSX to `headerProps.nav`:

```tsx
<ArdoRoot
  headerProps={{
    nav: (
      <ArdoNav>
        <ArdoNavLink to="/guide">Guide</ArdoNavLink>
        <ArdoNavLink to="/api">API</ArdoNavLink>
        <ArdoNavLink href="https://github.com/...">GitHub</ArdoNavLink>
      </ArdoNav>
    ),
  }}
/>
```

### Social Links

Pass social links to `headerProps.actions`:

```tsx
<ArdoRoot
  headerProps={{
    actions: <ArdoSocialLink href="https://github.com/..." icon="github" />,
  }}
/>
```

Supported icons: `github`, `twitter`, `discord`, `linkedin`, `youtube`, `npm`

### Footer

Pass footer content via `footerProps`:

```tsx
<ArdoRoot
  footerProps={{
    message: "Released under the MIT License.",
    copyright: "Copyright © 2024 Your Name",
    sponsor: { text: "Acme Corp", link: "https://acme.example" },
  }}
/>
```

### Search

Search is enabled by default. Customize the placeholder via `headerProps.searchPlaceholder`:

```tsx
<ArdoRoot
  headerProps={{
    searchPlaceholder: "Search docs...",
  }}
/>
```

### Edit Link & Last Updated

These are set as props on `ArdoRoot` and apply site-wide:

```tsx
<ArdoRoot
  editLink={{
    pattern: "https://github.com/user/repo/edit/main/docs/:path",
    text: "Edit this page on GitHub",
  }}
  lastUpdated={{
    enabled: true,
    text: "Last updated",
    formatOptions: { year: "numeric", month: "long", day: "numeric" },
  }}
/>
```

### TOC Label

```tsx
<ArdoRoot tocLabel="On this page" />
```

---

## Custom Theme

### CSS Variables

Override CSS variables to customize colors:

```css
:root {
  --ardo-color-brand: oklch(0.6 0.2 260);
  --ardo-color-brandLight: oklch(0.7 0.15 260);
  --ardo-color-brandDark: oklch(0.5 0.25 260);
}
```

### Runtime Hooks

- `useArdoConfig()` — Returns full site configuration
- `useArdoSiteConfig()` — Returns cross-cutting content settings (editLink, lastUpdated, tocLabel)
- `useArdoSidebar()` — Returns resolved sidebar items
- `useArdoPageData()` — Returns current page metadata
- `useArdoTOC()` — Returns table of contents items

### Component Overrides

Create custom components and use them in your layout instead of the defaults.

---

## TypeDoc Integration

Ardo includes built-in TypeDoc integration for auto-generating API documentation.

### Configuration

```ts
ardo({
  typedoc: {
    enabled: true,
    entryPoints: ['../src/index.ts'],
    tsconfig: '../tsconfig.json',
    out: 'api',
  },
})
```

### Options

- `entryPoints` — TypeScript entry files
- `tsconfig` — Path to tsconfig.json
- `out` — Output directory
- `excludePrivate` — Exclude private members
- `excludeInternal` — Exclude @internal members
- `markdown.sourceLinks` — Include source links
- `markdown.sourceBaseUrl` — Base URL for source links

---

## Deployment

Ardo produces a fully static site. When you run `pnpm build`, React Router prerenders every page to static HTML. The build output is in `build/client/`.

### GitHub Pages

1. Set `base` in `vite.config.ts` if deploying to a subdirectory
2. Create `.github/workflows/deploy.yml` with build and deploy steps
3. Enable GitHub Pages with source set to "GitHub Actions"

### Netlify / Vercel

- **Build command:** `pnpm build`
- **Output directory:** `build/client`

---

## Troubleshooting

### Installation Issues

**`Cannot find module 'ardo'`** — Install dependencies:

```bash
pnpm add ardo react react-dom react-router isbot
```

**Node.js Version Error** — Ardo requires Node.js 22+.

### Build Issues

**`Failed to resolve import`** — Ensure `vite.config.ts` has the Ardo plugin configured.

**TypeScript Errors** — Run `pnpm build` to regenerate types, restart TS server.

### Development Issues

**Hot Reload Not Working** — Check that you're editing files in `app/routes/`.

**Search Not Working** — Run `pnpm build` once to generate the search index.

### Deployment Issues

**Base Path Issues** — Set the `base` option in `vite.config.ts`.

---

## Package Exports Reference

| Export               | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| `ardo/vite`          | Vite plugin with React Router, MDX, and all config              |
| `ardo/runtime`       | React hooks: useArdoConfig, useArdoSiteConfig, useArdoSidebar  |
| `ardo/ui`            | UI components: Layout, Header, Sidebar, TOC, Footer             |
| `ardo/ui/styles.css` | Default theme stylesheet                                        |
| `ardo/typedoc`       | TypeDoc utilities: generateApiDocs                              |

### Key Types

- `ArdoConfig` — Main site configuration (build-time)
- `ArdoSiteConfig` — Cross-cutting content settings (editLink, lastUpdated, tocLabel)
- `SidebarItem` — Sidebar navigation item
- `NavItem` — Top navigation item
- `PageFrontmatter` — Frontmatter fields
- `PageData` — Runtime page data
- `TOCItem` — Table of contents entry

### Key Components

- `ArdoRoot` — All-in-one root component (provider + layout + header + sidebar + footer)
- `Layout` — Main page layout wrapper
- `Header` — Top navigation bar (props: logo, title, nav, actions, searchPlaceholder)
- `Sidebar` — Left sidebar navigation
- `TOC` — Right sidebar table of contents (props: label)
- `Footer` — Page footer (props: message, copyright, sponsor)
- `CodeBlock` — Syntax-highlighted code (supports plain text children in `.tsx` routes)
- `BareContent` — Renders imported MDX without article/footer wrapper
- `Search` — Full-text search dialog (props: placeholder)