# 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. [Theme Configuration](#theme-configuration)
6. [Custom Theme](#custom-theme)
7. [TypeDoc Integration](#typedoc-integration)
8. [Deployment](#deployment)
9. [Framework Comparison](#framework-comparison)
10. [Troubleshooting](#troubleshooting)
11. [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',

      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:

```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!
:::

#### 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
│   ├── entry.client.tsx      # Client entry
│   └── entry.server.tsx      # Server entry
├── vite.config.ts            # Vite + Ardo 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"`

### Container Directives

Highlight important information:

```markdown
:::tip
This is a helpful tip.
:::

:::warning
Be careful!
:::

:::danger
This action cannot be undone!
:::
```

### Code Groups

Display multiple code variants in tabs using `::: code-group`.

### 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

---

## Theme Configuration

Configure the theme via `themeConfig` in your `vite.config.ts`:

### Navigation

```ts
themeConfig: {
  nav: [
    { text: 'Guide', link: '/guide/introduction' },
    { text: 'API', link: '/api-reference' },
  ],
}
```

### Sidebar

```ts
themeConfig: {
  sidebar: [
    {
      text: 'Guide',
      items: [
        { text: 'Introduction', link: '/guide/introduction' },
      ],
    },
  ],
}
```

### Social Links

```ts
themeConfig: {
  socialLinks: [
    { icon: 'github', link: 'https://github.com/...' },
  ],
}
```

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

### Footer

```ts
themeConfig: {
  footer: {
    message: 'Released under the MIT License.',
    copyright: 'Copyright © 2024 Your Name',
  },
}
```

### Search

```ts
themeConfig: {
  search: {
    enabled: true,
    placeholder: 'Search docs...',
  },
}
```

### Edit Link

```ts
themeConfig: {
  editLink: {
    pattern: 'https://github.com/user/repo/edit/main/docs/:path',
    text: 'Edit this page on GitHub',
  },
}
```

---

## Custom Theme

### CSS Variables

Override CSS variables to customize colors:

```css
:root {
  --ardo-c-brand: #8b5cf6;
  --ardo-c-brand-light: #a78bfa;
  --ardo-c-brand-dark: #7c3aed;
}
```

### Runtime Hooks

- `useConfig()` — Returns full site configuration
- `useThemeConfig()` — Returns theme-specific configuration
- `useSidebar()` — Returns resolved sidebar items
- `usePageData()` — Returns current page metadata
- `useTOC()` — 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`

---

## Framework Comparison

|                  | Ardo            | VitePress     | Docusaurus   | Starlight     |
| ---------------- | --------------- | ------------- | ------------ | ------------- |
| **UI Framework** | React 19        | Vue 3         | React 18     | Astro         |
| **Build Tool**   | Vite            | Vite + Rollup | Webpack      | Vite + Rollup |
| **Router**       | React Router 7  | Vue Router    | React Router | Astro Router  |
| **Rendering**    | SSG + Hydration | SSG + SPA     | SSG + SPA    | Islands       |

### Key Differentiators

- **React ecosystem** — Use any React component, hook, or library
- **React Router 7** — Modern routing with type-safe navigation
- **TypeDoc built-in** — Auto-generate API docs from TypeScript source
- **JSX-first architecture** — Theme components accept explicit props

---

## 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: useConfig, useThemeConfig, useSidebar, etc. |
| `ardo/ui`            | UI components: Layout, Header, Sidebar, TOC, Footer      |
| `ardo/ui/styles.css` | Default theme stylesheet                                 |
| `ardo/typedoc`       | TypeDoc utilities: generateApiDocs                       |

### Key Types

- `PressConfig` — Main site configuration
- `ThemeConfig` — Theme settings (nav, sidebar, footer, search)
- `SidebarItem` — Sidebar navigation item
- `NavItem` — Top navigation item
- `PageFrontmatter` — Frontmatter fields
- `PageData` — Runtime page data
- `TOCItem` — Table of contents entry

### Key Components

- `Layout` — Main page layout wrapper
- `Header` — Top navigation bar
- `Sidebar` — Left sidebar navigation
- `TOC` — Right sidebar table of contents
- `Footer` — Page footer
- `CodeBlock` — Syntax-highlighted code
- `Search` — Full-text search dialog