Extraits réutilisables

L’un des principes fondamentaux du développement logiciel est DRY (Don’t Repeat Yourself), qui s’applique aussi à la documentation. Si vous vous retrouvez à répéter le même contenu à plusieurs endroits, créez un extrait personnalisé pour ce contenu. Les extraits contiennent du contenu que vous pouvez importer dans d’autres fichiers pour le réutiliser. Vous contrôlez l’endroit où l’extrait apparaît sur une page. Si vous devez un jour mettre à jour ce contenu, il vous suffit de modifier l’extrait plutôt que chaque fichier où l’extrait est utilisé.

Les snippets sont des fichiers .mdx, .md, .js ou .jsx importés dans un autre fichier. Vous pouvez placer les fichiers de snippets n’importe où dans votre projet.

Lorsque vous importez un snippet dans un autre fichier, celui-ci n’apparaît qu’à l’endroit où vous l’importez et n’est pas affiché comme une page autonome. Tout fichier dans le dossier /snippets/ est toujours un snippet, même s’il n’est pas importé dans un autre fichier.

Créez un fichier avec le contenu que vous souhaitez réutiliser. Les snippets peuvent contenir tous les types de contenu pris en charge par Mintlify et peuvent importer d’autres snippets. Consultez Snippets imbriqués pour savoir où déclarer les imports lors de l’imbrication.

Importez des snippets dans des pages en utilisant soit un chemin absolu, soit un chemin relatif.

• Imports absolus : commencez par / pour importer depuis la racine de votre projet.
• Imports relatifs : utilisez ./ ou ../ pour importer des snippets par rapport à l’emplacement du fichier courant.

Le nom utilisé pour rendre un snippet importé sous forme de balise JSX doit commencer par une lettre majuscule, comme MySnippet. MDX traite les balises commençant par une minuscule, comme <mySnippet />, comme des noms littéraux d’éléments HTML ou d’éléments personnalisés plutôt que comme des références à des snippets importés. Par convention, utilisez la PascalCase pour les noms de snippets.

1. Ajoutez à votre fichier de snippet le contenu que vous souhaitez réutiliser.

   Hello world! This is my content I want to reuse across pages.

2. Importez l’extrait dans votre fichier de destination à l’aide d’un chemin absolu ou relatif.

   Import absolu

   Import relatif

   ---
   title: "Une page d'exemple"
   description: "Ceci est une page d'exemple qui importe un extrait."
   ---
   
   import MySnippet from "/shared/my-snippet.mdx";
   
   Le contenu de l'extrait s'affiche sous cette phrase.
   
   <MySnippet />

Les snippets peuvent en importer d’autres. Déclarez l’import dans le fichier du snippet qui utilise le snippet imbriqué, et non dans la page qui importe le snippet parent.

Chaque fichier résout ses propres imports. Les imports déclarés dans une page ne s’appliquent pas aux snippets que la page importe. Un snippet imbriqué qui dépend d’un import déclaré au niveau de la page peut s’afficher comme du contenu vide.

1. Importez le snippet imbriqué dans le fichier du snippet parent. Déclarez l’import à l’endroit où vous souhaitez utiliser le snippet imbriqué.

   import ChildSnippet from "/shared/child-snippet.mdx";
   
   Ce snippet affiche un autre snippet sous cette phrase.
   
   <ChildSnippet />

2. N’importez que le snippet parent dans votre fichier de destination. Vous n’avez pas besoin d’importer le snippet imbriqué.

   ---
   title: "Une page d'exemple"
   description: "Ceci est une page d'exemple qui importe un snippet contenant un snippet imbriqué."
   ---
   
   import ParentSnippet from "/shared/parent-snippet.mdx";
   
   <ParentSnippet />

Faites référence à des variables issues d’un extrait dans une page.

1. Exportez des variables depuis un fichier de fragment.

   export const myName = "Ronan";
   
   export const myObject = { fruit: "strawberries" };
   
   ;

2. Importez l’extrait depuis votre fichier de destination et utilisez la variable.

   ---
   title: "Une page d'exemple"
   description: "Ceci est une page d'exemple qui importe un fragment avec des variables."
   ---
   
   import { myName, myObject } from "/shared/custom-variables.mdx";
   
   Bonjour, je m'appelle {myName} et j'aime {myObject.fruit}.

Utilisez des variables pour transmettre des données à un extrait lorsque vous l’importez.

1. Ajoutez des variables à votre extrait et transmettez des propriétés lorsque vous l’importez. Dans cet exemple, la variable est {word}.

   Mon mot-clé du jour est {word}.

2. Importez l’extrait dans votre fichier de destination en utilisant la variable. La propriété que vous transmettez remplace la variable dans la définition de l’extrait.

   ---
   title: "Une page d'exemple"
   description: "Ceci est une page d'exemple qui importe un extrait avec une variable."
   ---
   
   import MySnippet from "/shared/my-snippet.mdx";
   
   <MySnippet word="bananas" />

Les variables sont également interpolées à l’intérieur des blocs de code délimités. Cela est utile pour les extraits qui incluent des commandes d’installation ou d’autres exemples de code qui diffèrent selon le nom du package, la version ou l’environnement.

export const InstallSnippet = ({ packageName }) => <></>;

Installez le package :

```bash
npm install {packageName}
```

import InstallSnippet from "/shared/install-snippet.mdx";

<InstallSnippet packageName="@myorg/sdk" />

1. Créez un extrait avec un composant JSX. Voir Composants React pour en savoir plus.

   export const MyJSXSnippet = () => {
     return (
       <div>
         <h1>Bonjour, monde !</h1>
       </div>
     );
   };

2. Importez l’extrait.

   ---
   title: "Une page d'exemple"
   description: "Ceci est une page d'exemple qui importe un extrait avec un composant React."
   ---
   
   import { MyJSXSnippet } from "/components/my-jsx-snippet.jsx";
   
   <MyJSXSnippet />

Conservez des données telles qu’une liste de composants SDK, une matrice de compatibilité ou un ensemble de forfaits dans un seul snippet et affichez-les sur plusieurs pages. Lorsque vous modifiez les données, chaque tableau, liste ou carte construit à partir d’elles est mis à jour.

Stockez les données sous forme d’objet JSON simple dans un snippet .js avec un export nommé. Écrivez ensuite un snippet .jsx qui transforme les données en balisage.

export const sdkComponents = [
  { "name": "CardForm", "version": "2.4.0", "status": "Stable", "docs": "/components/card-form" },
  { "name": "PinReveal", "version": "1.9.2", "status": "Beta", "docs": "/components/pin-reveal" }
];

export const ComponentsTable = ({ rows }) => (
  <table>
    <thead>
      <tr>
        <th>Composant</th>
        <th>Version</th>
        <th>Statut</th>
      </tr>
    </thead>
    <tbody>
      {rows.map((row) => (
        <tr key={row.name}>
          <td><a href={row.docs}>{row.name}</a></td>
          <td><code>{row.version}</code></td>
          <td>{row.status}</td>
        </tr>
      ))}
    </tbody>
  </table>
);

---
title: "Composants SDK"
description: "Tous les composants du SDK, avec leur version actuelle et leur statut."
---

import { sdkComponents } from "/snippets/sdk-components.js";
import { ComponentsTable } from "/snippets/components-table.jsx";

Le SDK inclut {sdkComponents.length} composants.

<ComponentsTable rows={sdkComponents} />

## Composants stables

<ComponentsTable rows={sdkComponents.filter((row) => row.status === "Stable")} />

Si vous stockez des données dans un fichier JSON ou YAML, générez des snippets à partir de ces données sources. Utilisez un script pour écrire le snippet de données avec une page par entrée et créer le groupe de navigation correspondant. Exécutez le script en CI chaque fois que le fichier source change et validez le résultat.

import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { parse } from "yaml";

const components = parse(readFileSync("sdk-components.yaml", "utf8"));
const slug = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-");

// Un snippet avec toutes les données, pour les tableaux et listes n'importe où dans la documentation.
writeFileSync("snippets/sdk-components.js", `export const sdkComponents = ${JSON.stringify(components, null, 2)};\n`);

// Une page par composant.
mkdirSync("components", { recursive: true });
for (const component of components) {
  const page = `---
title: ${JSON.stringify(component.name)}
description: ${JSON.stringify(component.description)}
---

{/* Généré à partir de sdk-components.yaml par scripts/generate-docs.mjs. Modifiez le YAML, pas ce fichier. */}

| Champ | Valeur |
| --- | --- |
| Version | \`${component.version}\` |
| Statut | ${component.status} |
`;
  writeFileSync(`components/${slug(component.name)}.mdx`, page);
}

// Garder la navigation synchronisée : remplacer les pages du groupe nommé "Components", où qu'il se trouve.
const docs = JSON.parse(readFileSync("docs.json", "utf8"));
const findGroup = (node) => (Array.isArray(node) ? node.map(findGroup).find(Boolean) : node && typeof node === "object" ? (node.group === "Components" ? node : findGroup(Object.values(node))) : undefined);
const group = findGroup(docs.navigation);
if (group) {
  group.pages = components.map((component) => `components/${slug(component.name)}`);
  writeFileSync("docs.json", `${JSON.stringify(docs, null, 2)}\n`);
}

name: Generate docs from YAML

on:
  push:
    paths:
      - sdk-components.yaml
      - scripts/generate-docs.mjs
  workflow_dispatch:

permissions:
  contents: write

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install yaml
      - run: node scripts/generate-docs.mjs
      - name: Commit generated files
        run: |
          git add -A
          if git diff --cached --quiet; then
            echo "Nothing changed."
            exit 0
          fi
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git commit -m "docs: regenerate from sdk-components.yaml"
          git push