Markdown et MDX

Ardo privilégie Markdown sans vous y enfermer. Commencez par du texte et des blocs de code ; passez à MDX pour un exemple React interactif, un composant ou un encadré de design system, sans changer d’outils.

Noms des fichiers de pages

Les fichiers d’app/routes/ deviennent des URL. Choisissez des noms explicites comme guide/getting-started.mdx ou guide/c-sharp.mdx. Ardo refuse # et ? dans les noms de fichiers et dossiers : ils délimitent fragments et requêtes. Utilisez-les dans les titres et le contenu.

Syntaxe de base

Titres

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

Emphase

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

Listes

- Unordered item 1
- Unordered item 2
  - Nested item

1. Ordered item 1
2. Ordered item 2

Liens et images

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

GitHub Flavored Markdown

Ardo prend en charge GitHub Flavored Markdown (GFM) directement.

Tableaux

Listes de tâches

• Rédiger la documentation
• Ajouter la coloration syntaxique
• Déployer en production

Liens automatiques

Les URL deviennent automatiquement des liens :https://vite.dev

Coloration syntaxique

Ferromark colore les blocs de code au build avec son intégration native Ferriki. Grammaires et thèmes standards sont téléchargés et mis en cache à la première utilisation. Exemples :

interface User {
  id: string
  name: string
  email: string
}

function greetUser(user: User): string {
  return `Hello, ${user.name}!`
}

Surligner des lignes

Surlignez des lignes avec la syntaxe {lines}:

function example() {
  const highlighted = true
  const normal = false
  const alsoHighlighted = true
  const highlighted = true
  const notHighlighted = false
}

Numéros de ligne

Activez les numéros avec showLineNumbers:

const first = 1
const second = 2
const third = 3

Titre

Ajoutez un titre au bloc, combinable avec le surlignage :

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: {
    entryPoints: ["./src/index.ts"],
    tsconfig: "./tsconfig.json",
    title: "API Reference",
  },
})

Prompts

Utilisez le langage prompt pour le texte à copier dans un agent. Les lignes se replient au lieu de défiler horizontalement ; rédigez chaque paragraphe sur une seule ligne source :

```prompt
Add a Deployment page that explains the GitHub Pages workflow of this repository.
```

Groupes de code

Affichez plusieurs variantes de code dans des onglets :

function greet(name) {
  return `Hello, ${name}!`
}

function greet(name: string): string {
  return `Hello, ${name}!`
}

def greet(name):
    return f"Hello, {name}!"

Encadrés

Du Markdown sans imports : Ardo reconnaît les alertes GitHub et les associe aux encadrés correspondants.

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Negative potential consequences of an action.

Résultat :

Pour un titre personnalisé, utilisez les composants comme <Tip title="Pro Tip">, décrits dans Composants.

Composants

Les composants Ardo fonctionnent sans import dans MDX : encadrés, badges, cartes, onglets, accordéons, étapes, blocs de code et icônes. Composants les présente avec leur MDX et leurs props.

Vos composants

Importez les composants React et utilisez-les comme du HTML. Gardez-les hors d’app/routes/, par exemple dans app/components/: chaque fichier .tsx des routes devient une page.

import { MyComponent } from "../../components/MyComponent"

# My Page

<MyComponent prop="value" />

Fragments réutilisables

Ardo utilise des modules MDX standards : aucun plugin ou syntaxe spéciale n’est nécessaire pour partager du contenu. Placez les fragments dans snippets/ et importez-les où vous en avez besoin.

Définissez par exemple une note commune dans app/snippets/prerequisites.mdx. Un fragment intégré dans une autre page n’a pas besoin de frontmatter :

<Tip title="Before you start">
  This guide assumes you have {props.runtime} installed and can run packages with{" "}
  {props.packageManager}.
</Tip>

Importez-le dans une page MDX et placez-le dans ArdoBareContent pour retirer son wrapper de page :

import { ArdoBareContent } from "ardo/ui"
import Prerequisites from "../../snippets/prerequisites.mdx"

# Getting Started

<ArdoBareContent>
  <Prerequisites runtime="Node.js 22.22.0+" packageManager="pnpm" />
</ArdoBareContent>

Les fragments acceptent des props via des expressions MDX, composent des composants Ardo et vivent avec le code. Vite gère leurs imports et rechargements comme ceux des autres dépendances de route.

Dans les routes TSX

Un fichier .mdx importé en .tsx utilise normalement le wrapper Content complet : article, en-tête, pied et navigation. C’est utile pour une page entière, mais rarement pour un fragment. Placez-le dans ArdoBareContent pour l’intégrer comme contenu seul :

import { ArdoBareContent } from "ardo/ui"
import MySnippet from "./snippet.mdx"

export default function MyPage() {
  return (
    <ArdoBareContent>
      <MySnippet />
    </ArdoBareContent>
  )
}

Compilation MDX

Ferromark analyse .md et .mdx. MDX ajoute expressions JavaScript, imports, exports et composants JSX ; React compile le JSX via Vite. Utilisez le frontmatter YAML pour les métadonnées.

Ferromark compile chaque route en module MDX suivant le contrat de @mdx-js/mdx:

• import et export sont du JavaScript. La syntaxe TypeScript est refusée ; déplacez le code typé dans un module .ts importé.
• Les composants importés sont utilisés directement. Les autres viennent d’Ardo, puis de la prop components. Une erreur nomme tout composant manquant.
• export default devient la mise en page et remplace le wrapper Ardo : votre layout entoure la page au lieu d’ArdoDocContent.
• Le JSX dans une expression comme {items.map((item) => <Card />)} n’accède pas aux composants Ardo : importez-les explicitement.
• Les noms _components, _createMdxContent, _missingMdxReference, _provideComponents, MDXLayout, MDXContent, _ArdoPageDataProvider, _ardoFrontmatter, _ardoRoute et _ardoToc sont réservés. Les déclarer provoque une erreur de compilation.

Frontmatter

Ajoutez les métadonnées avec le frontmatter YAML :

---
title: Page Title
description: Page description for SEO
order: 2
---

Toutes les options figurent dans la référence du frontmatter.