Bien démarrer

Donnez cette phrase à votre agent de développement, dans un dépôt neuf ou existant. Le lien le dirige vers les instructions versionnées pour les agents. Il adapte l’exemple Basic testé et indique le résultat du contrôle des types, des tests et du build. Vous relisez le résultat comme toute autre pull request.

Sans agent, suivez l’installation manuelle ci-dessous.

Prérequis

Vous aurez besoin de :

• Node.js 22.22.0 ou ultérieur
• Linux ou Windows sur x64/arm64, ou macOS sur Apple Silicon, avec les dépendances natives optionnelles activées
• pnpm (recommandé), npm ou yarn

Structure du projet

Voici un projet Ardo. Les fichiers sous app/routes/ deviennent des pages, app/root.tsx contient l’interface du site et le reste relève de la configuration :

my-docs/
├── app/
│   ├── routes/                  # Pages: .md, .mdx, and .tsx files
│   │   ├── guide/
│   │   │   └── getting-started.mdx
│   │   └── home.tsx             # Home page
│   └── root.tsx                 # Optional: theme, logo, header, sidebar, footer
├── ardo.config.ts               # Optional site configuration
├── vite.config.ts               # Optional extra Vite plugins or settings
├── pnpm-workspace.yaml          # pnpm build-script allowlist, when using pnpm
├── tsconfig.json
└── package.json

Installation manuelle

Ces étapes créent un nouveau projet de documentation. Dans un dépôt existant, placez-le dans son propre paquet ou répertoire : Ardo construit un site statique indépendant, sans partager le routeur ni les points d’entrée de votre application.

1. Créer un projet

mkdir my-docs
cd my-docs
pnpm init

2. Installer les dépendances

pnpm add ardo@6
pnpm add -D typescript@6

TypeScript 6 ou ultérieur vérifie les types d’un site Ardo. La documentation API optionnelle nécessite une nightly TypeScript 7.1 épinglée ; utilisez-la lorsque vous ajoutez api.

3. Ajouter les scripts

Ardo gère React, React DOM et Vite comme ses propres dépendances. Sa CLI lance le serveur de développement, construit le site statique et prévisualise la sortie client générée :

{
  "scripts": {
    "dev": "ardo dev",
    "build": "ardo build",
    "preview": "ardo preview"
  }
}

Avec pnpm, ajoutez une liste de scripts de build autorisés pour qu’esbuild puisse préparer la dépendance native de Vite :

# pnpm-workspace.yaml
packages:
  - "."

allowBuilds:
  esbuild: true

4. Ajouter une configuration Ardo optionnelle

Ardo fonctionne sans fichier de configuration. Ajoutez ardo.config.ts pour les métadonnées du site, le déploiement ou le contenu. Le thème, la navigation, la barre latérale et le pied de page se configurent dans les props JSX de root.tsx:

ardo.config.ts:

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  title: "My Documentation",
  description: "My awesome documentation site",
})

Le site est servi à la racine du domaine. Pour un sous-chemin, par exemple un site de projet GitHub Pages, définissez base. Le guide de déploiement couvre les hébergeurs.

Ajoutez vite.config.ts uniquement pour des plugins supplémentaires ou des paramètres propres à Vite. La CLI Ardo ajoute automatiquement son intégration ; il n’est donc pas nécessaire d’appeler ardo() dans votre configuration Vite.

5. Créer les fichiers de l’application

Le contenu seul forme déjà un site : sans app/root.tsx, Ardo rend <ArdoRoot />, soit un en-tête avec recherche et sélecteur de thème, une section latérale par dossier de app/routes/ et un pied de page. Ardo rend aussi la structure HTML, génère la table des routes et fournit les points d’entrée client et serveur, la configuration et les styles. Ajoutez app/root.tsx dès que vous voulez votre propre thème, logo ou interface ; son export par défaut est le composant racine.

app/root.tsx:

import { ArdoRoot } from "ardo/ui"

export default function Root() {
  return <ArdoRoot />
}

Passez ArdoHeader, ArdoSidebar ou ArdoFooter en enfants pour personnaliser l’interface, par exemple pour ajouter un lien de navigation :

import { ArdoHeader, ArdoNav, ArdoNavLink, ArdoRoot } from "ardo/ui"

export default function Root() {
  return (
    <ArdoRoot>
      <ArdoHeader>
        <ArdoNav>
          <ArdoNavLink to="/guide/getting-started">Guide</ArdoNavLink>
        </ArdoNav>
      </ArdoHeader>
    </ArdoRoot>
  )
}

Mise en page et navigation décrit les sections latérales, le pied de page et les exports optionnels Layout et ErrorBoundary de root.tsx.

tsconfig.json:

{
  "extends": "ardo/tsconfig",
  "include": ["app/**/*", "*.ts"]
}

Le preset définit jsx, jsxImportSource: "ardo" et les déclarations Ardo. Les imports React, MDX et virtual: sont ainsi vérifiés sans autre configuration.

Importez les composants depuis ardo/ui, les API d’exécution comme ArdoLink et useArdoPath depuis ardo/runtime, et les hooks React depuis ardo/react. Ardo fournit React : le paquet de documentation n’a pas besoin de sa propre dépendance React.

6. Créer les premières pages

Créez une page d’accueil pour donner une destination à l’URL racine et au logo de l’en-tête :

app/routes/home.tsx:

import { ArdoHero } from "ardo/ui"

export default function HomePage() {
  return (
    <ArdoHero
      name="My Documentation"
      tagline="Guides and examples for your project."
      actions={[{ text: "Get started", link: "/guide/getting-started", theme: "brand" }]}
    />
  )
}

Ajoutez le guide auquel renvoient l’accueil, l’en-tête et la barre latérale :

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

---
title: Getting Started
---

# Getting Started

Welcome to your documentation site!

Exécutez pnpm dev et ouvrez http://localhost:5173. Votre accueil devrait apparaître ; choisissez Get started pour ouvrir le guide.

Développement

Lancez le serveur de développement :

pnpm dev

Votre site fonctionne sur http://localhost:5173. Le serveur Vite prend en charge les modifications des routes MDX et TSX.

Build de production

Lorsque vous êtes prêt à publier :

pnpm build

La sortie se trouve dans build/client/: un index.html prérendu par page, une 404.html et les ressources avec empreinte de contenu, prêts pour tout hébergeur statique. Le build doit annoncer deux pages prérendues et aucun lien interne cassé. Il vérifie chaque lien et ancre du HTML généré. Prévisualisez le site localement avant de le déployer :

pnpm preview

Étapes suivantes

Votre site fonctionne. Personnalisez-le :

• Ajoutez pages, sections latérales, logo et liens d’en-tête avec Mise en page et navigation
• Enrichissez vos contenus avec Markdown et MDX et les composants intégrés
• Modifiez couleurs et styles avec les thèmes, dont Tailwind CSS en option
• Déployez votre site sur GitHub Pages, Netlify, Vercel ou tout hébergeur statique
• Générez des pages de référence avec la documentation API