Configuration

La CLI lit la configuration facultative dans ardo.config.ts. La plupart des sites n’ont pas besoin de configuration Vite : ardo dev, ardo build et ardo preview fournissent l’intégration. Configurez l’interface en React avec ArdoRoot, les props d’en-tête, de barre latérale et de pied de page, les composants et les hooks d’exécution.

Cette page décrit les options du site et du build, puis les composants et hooks React. Les projets Vite existants peuvent conserver ardo() pendant la migration. Consultez Versions pour une vue d’ensemble, y compris des fonctionnalités prévues.

Configuration de base

import { defineArdoConfig } from "ardo/config"

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

defineArdoConfig() accepte les mêmes options que le plugin Vite. Ajoutez vite.config.ts uniquement pour d’autres plugins ou réglages Vite ; la CLI fournit automatiquement les plugins Ardo.

Par exemple, configurez le serveur de développement sans ajouter d’appel à ardo():

import { defineConfig } from "ardo/vite"

export default defineConfig({
  server: { port: 4000 },
})

Ardo réexporte defineConfig: aucune dépendance directe à Vite n’est nécessaire.

Les deux fichiers peuvent exporter un objet, une promesse ou une fonction recevant l’environnement de configuration Vite. Modifier un fichier existant redémarre le serveur automatiquement. Après l’ajout ou la suppression d’un fichier, relancez ardo dev.

Lors d’une migration, déplacez les options de ardo({...}) vers ardo.config.ts avant de retirer le plugin. Ardo signale une erreur si les deux formes restent actives.

Configuration du site

Ces options définissent l’identité et le comportement général du site.

title

• Type :string
• Défaut : le champ name de package.json, sinon "Ardo"

Titre du site utilisé dans le <title> par défaut et l’en-tête. Définissez-le dans ardo.config.ts quand le nom du paquet ne convient pas comme titre.

defineArdoConfig({
  title: "My Documentation",
})

description

• Type :string
• Défaut :""

Description du site pour les métadonnées par défaut.

defineArdoConfig({
  title: "My Docs",
  description: "A comprehensive guide to my library",
})

titleSeparator

• Type :string
• Défaut :" | "

Séparateur entre le titre de page et celui du site dans <title>. Par exemple, « Getting Started » devient Getting Started | My Docs.

defineArdoConfig({
  title: "My Docs",
  titleSeparator: " - ",
})

base

• Type :string
• Défaut :"/"

Chemin de base du site. Définissez-le pour un déploiement sous un sous-chemin.

defineArdoConfig({
  title: "My Docs",
  base: "/docs/",
})

siteUrl

• Type :string
• Défaut :""

URL publique absolue du site. Ardo l’utilise pour les URL canoniques, og:url et les URL absolues des images sociales des routes Markdown.

defineArdoConfig({
  title: "My Docs",
  siteUrl: "https://example.com",
})

Configurez base séparément pour un sous-chemin. Ardo combine siteUrl, base et la route pour les URL canoniques.

metadata

• Type :{ image?: string; ogType?: string; twitterCard?: "summary_large_image" | "summary"; twitterSite?: string }
• Défaut :{}

Valeurs par défaut des métadonnées Markdown. Le frontmatter peut les remplacer pour chaque page.

defineArdoConfig({
  title: "My Docs",
  siteUrl: "https://example.com",
  metadata: {
    image: "/social.png",
    ogType: "website",
    twitterCard: "summary_large_image",
    twitterSite: "@example",
  },
})

seo.llms

• Type :boolean | { indexFileName?: string; fullFileName?: string; includeFull?: boolean; title?: string; description?: string }
• Défaut :true

Génère des fichiers texte adaptés aux LLM avec les autres sorties du build :

• /llms.txt est un index Markdown concis des routes Markdown et MDX. Il suit la barre latérale : sections dans l’ordre des onglets, pages selon order, pour présenter le guide avant la référence aux agents. Chaque référence API ou OpenAPI générée apparaît comme un lien vers son index.
• /llms-full.txt regroupe toutes les pages dans le même ordre. Chacune commence par un titre ## et ses propres titres descendent d’un niveau.

Avec la gestion des versions, les deux fichiers existent aussi sous la version courante, par exemple /v6/llms.txt et /v6/llms-full.txt. L’index versionné pointe vers son texte intégral. Conservez-les avec les anciens instantanés HTML ; les fichiers racine restent des alias de la version courante.

Ardo utilise les titres et descriptions du frontmatter, ignore les routes TSX et retire les imports, exports et balises JSX du texte intégral. llms: false dans le frontmatter exclut une page Markdown des deux fichiers.

defineArdoConfig({
  title: "My Docs",
  siteUrl: "https://example.com",
  seo: {
    llms: {
      title: "My Docs",
      description: "Developer documentation for my package.",
      includeFull: true,
    },
  },
})

Définissez seo.llms: false pour gérer ces fichiers dans public/.

seo.sitemap

• Type :boolean | { changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never"; priority?: number; exclude?: string[] }
• Défaut :true

Génère /sitemap.xml à partir des routes Markdown, MDX et TSX. Ardo combine siteUrl, base et la route pour produire des URL absolues, même sous un sous-chemin.

defineArdoConfig({
  title: "My Docs",
  siteUrl: "https://example.com",
  base: "/docs/",
  seo: {
    sitemap: {
      changefreq: "weekly",
      priority: 0.7,
      exclude: ["/kit"],
    },
  },
})

seo.sitemap: false désactive la génération. sitemap: false dans le frontmatter exclut une route Markdown. seo.sitemap.exclude accepte des préfixes, y compris pour TSX : /kit exclut /kit et /kit/buttons, mais pas /kitchen. La barre finale est facultative. Les préfixes précèdent ceux du déploiement, de version et de langue. Cette option ne règle que l’inclusion dans le sitemap ; configurez séparément les métadonnées robots pour noindex.

seo.robots

• Type :boolean | { allow?: string[]; disallow?: string[] }
• Défaut :true

Génère /robots.txt. Par défaut, Ardo autorise tous les robots et pointe vers le sitemap lorsque siteUrl est défini.

defineArdoConfig({
  title: "My Docs",
  siteUrl: "https://example.com",
  seo: {
    robots: {
      allow: ["/"],
      disallow: ["/drafts/"],
    },
  },
})

Définissez seo.robots: false pour fournir votre robots.txt depuis public/.

linkCheck

• Type :{ enabled?: boolean; checkAnchors?: boolean; exclude?: string[]; level?: "warn" | "error" }
• Défaut :{ enabled: true, checkAnchors: true, level: "warn" }

Vérifie les liens internes du build avec ferrolink. Après l’écriture des pages par ardo build, Ardo vérifie liens, images, scripts, feuilles de style, candidats srcset et redirections meta de tout le HTML, issu de Markdown, de composants ou de pages générées. Il vérifie aussi les destinations dans _redirects et vercel.json et les chemins de version dans versions.json. Par défaut, chaque #fragment doit correspondre à un identifiant de la page cible. Les sources de redirection sont valides puisqu’Ardo génère leurs pages.

Les liens externes sont exclus car leur disponibilité dépend de serveurs tiers. Les autres versions de versioning sont considérées comme présentes, chacune étant déployée séparément. Un lien hors de la base de déploiement, tel /guide/ sous /docs/, est signalé. Chaque diagnostic indique le fichier et la ligne.

exclude contient des globs de cibles à ignorer. Avec / initial, le motif couvre le chemin URL complet, base comprise, comme /generated/** ou /blog/** pour une autre application du même hôte. Les autres motifs sont relatifs à la base. Une cible ignorée ne produit de diagnostic ni pour fichier ni pour ancre absente.

defineArdoConfig({
  title: "My Docs",
  linkCheck: {
    level: "error",
    exclude: ["/generated/**"],
  },
})

Utilisez checkAnchors: false si un autre outil réécrit les identifiants après la lecture du manifeste. Réservez enabled: false aux projets dont un autre vérificateur contrôle le build.

validation

• Type :{ frontmatter?: { invalid?: "warn" | "error" | "ignore"; unknown?: "warn" | "error" | "ignore" } }
• Défaut : avertissement pour les champs invalides ; champs inconnus ignorés pour compatibilité.

Ardo valide les champs documentés du frontmatter lors du parcours des routes. Les diagnostics citent le fichier ; les valeurs invalides n’alimentent ni navigation, ni recherche, ni sitemap, ni redirections, ni sorties LLM. Activez le mode strict pour faire échouer la CI sur les fautes :

defineArdoConfig({
  title: "My Docs",
  validation: {
    frontmatter: {
      invalid: "error",
      unknown: "error",
    },
  },
})

Utilisez unknown: "warn" pendant l’adoption du mode strict. Gardez le défaut uniquement si un autre outil gère intentionnellement des champs personnalisés.

redirects

• Type :Array<{ from: string; to: string }>
• Défaut :[]

Génère les fichiers de redirection statique pour les anciens chemins configurés :

• _redirects pour les hébergeurs compatibles Netlify
• Entrées dansvercel.json
• Pages HTML pour les hébergeurs de fichiers statiques

defineArdoConfig({
  title: "My Docs",
  redirects: [
    { from: "/old-guide", to: "/guide/getting-started" },
    { from: "/v1/config", to: "/guide/configuration" },
  ],
})

Utilisez redirectFrom dans le frontmatter si la redirection appartient à une page précise.

versioning

• Type :false | { current: string; versions: Array<{ id: string; label?: string; path: string; locales?: string[] }>; rootRedirect?: boolean }
• Défaut :false

Active les versions majeures de documentation. Ardo construit sous le chemin courant, expose les versions au sélecteur, écrit /versions.json et génère par défaut une redirection /index.html vers la version courante.

Chaque version peut définir locales: omettez-le pour conserver la langue, utilisez [] pour une archive sans préfixe, ou listez les langues prises en charge. À défaut de la langue courante, la première est choisie. Le sélecteur se trouve en bas de la barre latérale, dans le pied des pages libres et dans le menu mobile. Classez les versions de la plus récente à la plus ancienne ; les anciennes affichent un bandeau vers la même page de la dernière version.

defineArdoConfig({
  title: "My Docs",
  siteUrl: "https://docs.example.com",
  versioning: {
    current: "v3",
    versions: [
      { id: "v3", label: "3.x", path: "/v3/" },
      { id: "v2", label: "2.x", path: "/v2/" },
    ],
  },
})

Ardo ajoute le chemin de version à base: base: "/my-project/" et path: "/v3/" donnent /my-project/v3/. Le sitemap ne couvre que le build courant. Les anciennes versions peuvent rester dans des dossiers statiques sans apparaître comme contenu courant dupliqué.

rootRedirect: false permet une page racine ou une redirection gérée par l’hébergeur. Sur GitHub Pages et les autres hébergeurs statiques, Ardo utilise du HTML avec meta refresh et JavaScript. Configurez les redirections HTTP du CDN ou de l’hébergeur en dehors d’Ardo.

i18n

• Type :false | { defaultLocale: string; locales: Array<{ id: string; label?: string }>; redirectUnlocalized?: boolean }
• Défaut :false

Ardo construit chaque langue comme une arborescence statique et affiche un sélecteur si plusieurs sont configurées. Placez les traductions sous app/routes/<locale>/, par exemple app/routes/en/guide/getting-started.mdx et app/routes/de/guide/getting-started.mdx.

Chaque route visible doit exister dans chaque langue configurée. Une traduction manquante ou une page hors des dossiers de langue fait échouer le build. Aucun repli à l’exécution ne change silencieusement la langue. La recherche ne charge que la langue active. Avec siteUrl, Ardo génère les liens canoniques et alternatifs. Traduisez l’interface via ArdoRoot et lisez la langue avec useArdoLocale(). Internationalisation présente l’exemple Palamedes complet.

Ardo inclut toujours la langue dans les URL canoniques publiques. Avec les versions, le segment de version vient en premier :

defineArdoConfig({
  title: "My Docs",
  versioning: {
    current: "v3",
    versions: [{ id: "v3", label: "3.x", path: "/v3/" }],
  },
  i18n: {
    defaultLocale: "en",
    locales: [
      { id: "en", label: "English" },
      { id: "de", label: "Deutsch" },
    ],
  },
})

Cela produit des URL comme /v3/en/guide/getting-started. La racine redirige vers la version courante et la langue par défaut ; la racine de version vers cette langue. Son préfixe reste visible. Le shell est app/root.tsx, pas un document localisé. redirectUnlocalized: true redirige les anciens chemins sans préfixe vers la langue par défaut, en développement et dans le build statique.

outDir

• Type :string
• Défaut :"build"

Dossier de sortie relatif au projet ou absolu. Le site statique est écrit dans <outDir>/client/ et le bundle serveur du build dans <outDir>/server/. ardo preview utilise ce même dossier client.

defineArdoConfig({
  title: "My Docs",
  outDir: "release/docs",
})

Le site se trouve alors dans release/docs/client/. Déployez ce dossier plutôt que build/client/. Le bundle serveur sert uniquement au build.

Ardo vide les deux dossiers par défaut. ardo build --no-emptyOutDir conserve les fichiers. build.emptyOutDir dans vite.config.ts applique la même règle ; les réglages de environments.client.build.emptyOutDir ou environments.ssr.build.emptyOutDir ont priorité.

lang

• Type :string
• Défaut :"en"

Langue du site pour l’attribut lang de <html>.

defineArdoConfig({
  title: "My Docs",
  lang: "de",
})

sidebar.sectionOrder

• Type :string[]
• Défaut :[]

Ordre des sections principales d’ArdoGeneratedSidebar. Utilisez les noms de dossiers sans barre initiale. Les sections listées viennent d’abord ; les autres suivent l’ordre généré habituel.

defineArdoConfig({
  title: "Product Docs",
  sidebar: {
    sectionOrder: ["guide", "reference", "api", "quality", "architecture", "archive"],
  },
})

Les sous-pages conservent l’ordre du champ order, puis le tri alphabétique de secours.

head

• Type :HeadConfig[]
• Statut : Ignoré

Ardo 6 ne rend plus ces balises. Exportez meta depuis root.tsx ou une route, avec le type ArdoMetaFunction d’ardo/runtime.

vite

• Type :Record<string, unknown>

Réservé aux données d’intégration liées à Vite. Placez les réglages Vite dans un vite.config.ts facultatif, fusionné par la CLI avec son intégration.

project

• Type :{ name?: string; homepage?: string; repository?: string; version?: string; author?: string; license?: string }

Métadonnées du projet exposées par virtual:ardo/config, détectées dans package.json si possible.

Options d’intégration

Ces options contrôlent les routes et les intégrations du build via defineArdoConfig() dans ardo.config.ts. Les projets Vite peuvent continuer à les passer à ardo() pendant la migration.

routes

• Type :ArdoRoutesPluginOptions | false
• Défaut : automatique

Configuration de la génération automatique des routes. false la désactive entièrement.

icons

• Type :false
• Défaut : icônes de chouette générées

Ardo génère les icônes de chouette /favicon.ico, /icon.svg et /apple-touch-icon.png au build et les sert en développement. Importez votre icône avec ArdoRoot, <ArdoRoot icon={icon} />, pour le fingerprint Vite ; voir Thèmes. Un fichier homonyme dans public/ remplace l’icône générée. icons: false vous confie les trois.

content

• Type :Array<{ from: string; to: string; frontmatter?: (file) => Record<string, string | number | boolean | string[] | undefined> }>
• Défaut :[]

Transforme du Markdown et MDX extérieur au dossier des routes en routes générées. Publiez ainsi des ADR, CHANGELOG.md ou README de paquets sans déplacer leur source canonique.

defineArdoConfig({
  title: "My Docs",
  content: [
    {
      from: "./adr",
      to: "decisions",
      frontmatter: (file) => ({
        description: `Copied from ${file.relativePath}`,
      }),
    },
    {
      from: "./CHANGELOG.md",
      to: "changelog",
    },
  ],
})

Ardo écrit sous routesDir/<to>/ et ajoute .ardo-generated. Il refuse de remplacer un dossier non vide sans ce marqueur. Sans frontmatter, title vient du premier titre # ou du nom de fichier, et order d’un préfixe numérique tel 0001-.

Lorsque from désigne un fichier unique, Ardo l’écrit sous routesDir/<to>/index.md ou routesDir/<to>/index.mdx. Ainsi, to: "changelog" devient la route /changelog.

Les sources de contenu ne réécrivent pas les liens relatifs et ne valident pas le frontmatter. Utilisez collections pour un schéma et des données typées.

collections

• Type :Record<string, { from: string; to: string; schema?: (data) => T }>
• Défaut :{}

Comme content, transforme les fichiers locaux en routes, et fournit aussi des données typées aux pages React personnalisées. schema valide le frontmatter au build. Lisez les données avec getCollection de virtual:ardo/collections.

import { defineArdoConfig } from "ardo/config"
import { defineCollection } from "ardo/vite"

const recipes = defineCollection<{ title: string }>({
  from: "./recipes",
  to: "recipes",
  schema: (data) => ({ title: String(data.title) }),
})

export default defineArdoConfig({ title: "My Docs", collections: { recipes } })

Sources de contenu décrit le parcours complet.

openapi

• Type :{ spec: string; out?: string }
• Défaut : aucun

Génère une référence statique depuis un fichier local OpenAPI 3.0 ou 3.1, JSON ou YAML. out vaut api par défaut. Voir Documentation API.

defineArdoConfig({
  title: "Pet API",
  openapi: { spec: "./openapi.yaml" },
})

routesDir

• Type :string
• Défaut :"./app/routes"

Dossier des fichiers de route.

defineArdoConfig({
  title: "My Docs",
  routesDir: "./src/routes",
})

Markdown

Les options Markdown se configurent sous markdown.

defineArdoConfig({
  title: "My Docs",
  markdown: {
    theme: { light: "github-light-default", dark: "github-dark-default" },
    lineNumbers: true,
  },
})

markdown.theme

• Type : ThemeInput | { light: ThemeInput; dark: ThemeInput } de@ferriki/core
• Défaut :{ light: "github-light-default", dark: "github-dark-default" }

Thème de coloration syntaxique. Ferriki accepte un nom, un thème TextMate personnalisé ou une paire clair/sombre. Les thèmes standards sont téléchargés et mis en cache au premier usage.

markdown: {
  theme: "one-dark-pro",
}

markdown.lineNumbers

• Type :boolean
• Défaut :false

Affiche les numéros de ligne des blocs de code.

markdown.anchor

• Type :boolean
• Défaut :true

Active les liens d’ancrage des titres.

markdown.toc

• Type :{ level?: [number, number] }
• Défaut :{ level: [2, 3] }

Configuration du sommaire. level fixe les niveaux minimal et maximal des titres inclus.

markdown: {
  toc: {
    level: [2, 4], // Include h2, h3, and h4
  },
}

markdown.passes

• Type : NativePassOptions[] deferromark
• Défaut :[]

Exécute les transformations natives de Ferromark dans l’ordre du tableau. Les titres transformés alimentent la page, le sommaire, la recherche et la validation des liens.

markdown: {
  passes: [
    { kind: "typography", language: "en" },
    { kind: "emojiShortcodes" },
    { kind: "githubReferences", repository: "owner/repository" },
  ],
}

markdown.typography est un raccourci pour une passe typographique. Configurez typography ou passes: Ferromark refuse leur combinaison.

Syntaxe Markdown native

Les options Ferromark se placent directement sous markdown. Tableaux GFM, texte barré, tâches, liens automatiques, notes et encadrés sont activés. Extensions facultatives : headingAttributes, imageAttributes, extendedAttributes, definitionLists, insertions, superscript, subscript, math et lineComments.

headingOffset décale ensemble les niveaux des titres et du sommaire. headingIdPrefix préfixe tous les identifiants natifs. Consultez l’API Node de Ferromark pour les détails.

Ardo gère le format, le frontmatter YAML, les composants React et le retrait du premier titre identique au titre de page. Les anciennes options remark, rehype et recma ont été supprimées ; voir Passer à Ardo 5.

Documentation API

api génère la documentation avec TypeScript natif et OXC au build et en développement. true utilise src/index.ts et tsconfig.json ; un objet configure un projet, un tableau plusieurs. Un objet exige entryPoints et tsconfig ; out vaut api-reference par défaut et title vaut API Reference. Les chemins de sortie doivent être distincts et non imbriqués.

Documentation API décrit installation, configuration, usage programmatique et limites. L’option typedoc et ses exports ont été supprimés ; voir Migration depuis TypeDoc.

Configuration de l’interface

Configurez navigation, sections, pied de page, editLink, lastUpdated et recherche avec JSX et <ArdoRoot> dans root.tsx. Mise en page et navigation documente ArdoRoot, l’en-tête, le pied et les sections de navigation.

Exports du paquet

Ardo sépare les imports utilisables dans le navigateur de ceux du build Node.js :

Frontmatter

La configuration par page utilise le frontmatter MDX. Consultez Frontmatter pour toutes les options.

Exemple de compatibilité du plugin Vite

Cette forme reste compatible avec les projets gérant Vite directement. Les nouveaux sites devraient utiliser ardo.config.ts et ajouter Vite seulement pour leurs intégrations. Utilisez cette forme à la place d’ardo.config.ts, et importez defineConfig d’Ardo pour éviter une dépendance Vite directe. Ajoutez la génération API selon Documentation API.

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

export default defineConfig({
  plugins: [
    ardo({
      title: "My Library",
      description: "Comprehensive documentation for My Library",
      lang: "en",

      markdown: {
        theme: { light: "github-light-default", dark: "github-dark-default" },
        lineNumbers: false,
        toc: { level: [2, 3] },
      },
    }),
  ],
})