Guide de contribution à la documentation

Bienvenue dans le Guide de contribution à la documentation Next.js ! Nous sommes ravis de vous accueillir ici.

Cette page fournit des instructions sur comment modifier la documentation de Next.js. Notre objectif est de permettre à chaque membre de la communauté de se sentir habilité à contribuer et améliorer nos docs.

Pourquoi contribuer ?

Le travail open-source n'est jamais terminé, et la documentation non plus. Contribuer aux docs est une excellente façon pour les débutants de s'impliquer dans l'open-source et pour les développeurs expérimentés de clarifier des sujets complexes tout en partageant leurs connaissances avec la communauté.

En contribuant à la documentation Next.js, vous nous aidez à construire une ressource d'apprentissage plus robuste pour tous les développeurs. Que vous ayez trouvé une faute de frappe, une section confuse ou que vous ayez réalisé qu'un sujet particulier manque, vos contributions sont les bienvenues et appréciées.

Comment contribuer

Le contenu des docs se trouve dans le dépôt Next.js. Pour contribuer, vous pouvez éditer les fichiers directement sur GitHub ou cloner le dépôt et éditer les fichiers localement.

Workflow GitHub

Si vous êtes nouveau sur GitHub, nous recommandons de lire le Guide Open Source GitHub pour apprendre comment forker un dépôt, créer une branche et soumettre une pull request.

Bon à savoir : Le code sous-jacent des docs vit dans une base de code privée qui est synchronisée avec le dépôt public Next.js. Cela signifie que vous ne pouvez pas prévisualiser les docs localement. Cependant, vous verrez vos changements sur nextjs.org après la fusion d'une pull request.

Écrire en MDX

Les docs sont écrits en MDX, un format markdown qui supporte la syntaxe JSX. Cela nous permet d'embarquer des composants React dans les docs. Voir le Guide Markdown GitHub pour un aperçu rapide de la syntaxe markdown.

VSCode

Prévisualiser les changements localement

VSCode a un prévisualiseur markdown intégré que vous pouvez utiliser pour voir vos modifications localement. Pour activer le prévisualiseur pour les fichiers MDX, vous devrez ajouter une option de configuration à vos paramètres utilisateur.

Ouvrez la palette de commandes (⌘ + ⇧ + P sur Mac ou Ctrl + Shift + P sur Windows) et recherchez Preferences: Open User Settings (JSON).

Puis, ajoutez la ligne suivante à votre fichier settings.json :

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

Ensuite, ouvrez à nouveau la palette de commandes et recherchez Markdown: Preview File ou Markdown: Open Preview to the Side. Cela ouvrira une fenêtre de prévisualisation où vous pourrez voir vos modifications formatées.

Extensions

Nous recommandons aussi les extensions suivantes pour les utilisateurs de VSCode :

• MDX : Intellisense et coloration syntaxique pour MDX.
• Grammarly : Correcteur grammatical et orthographique.
• Prettier : Formater les fichiers MDX à l'enregistrement.

Processus de revue

Une fois votre contribution soumise, les équipes Next.js ou Developer Experience examineront vos changements, fourniront des retours et fusionneront la pull request lorsqu'elle sera prête.

N'hésitez pas à nous faire savoir si vous avez des questions ou besoin d'assistance supplémentaire dans les commentaires de votre PR. Merci de contribuer à la documentation Next.js et de faire partie de notre communauté !

Astuce : Exécutez pnpm prettier-fix pour lancer Prettier avant de soumettre votre PR.

Structure des fichiers

Les docs utilisent le routage par système de fichiers. Chaque dossier et fichier dans /docs représente un segment de route. Ces segments sont utilisés pour générer les URLs, la navigation et les fil d'Ariane.

La structure des fichiers reflète la navigation que vous voyez sur le site, et par défaut, les éléments de navigation sont triés alphabétiquement. Cependant, nous pouvons changer l'ordre des éléments en préfixant un nombre à deux chiffres (00-) au nom du dossier ou fichier.

Par exemple, dans la référence API des fonctions, les pages sont triées alphabétiquement car cela facilite la recherche d'une fonction spécifique pour les développeurs :

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

Mais, dans la section routage, les fichiers sont préfixés avec un nombre à deux chiffres, triés dans l'ordre où les développeurs devraient apprendre ces concepts :

02-routing
├── 01-defining-routes.mdx
├── 02-pages-and-layouts.mdx
├── 03-linking-and-navigating.mdx
└── ...

Pour trouver rapidement une page, vous pouvez utiliser ⌘ + P (Mac) ou Ctrl + P (Windows) pour ouvrir la barre de recherche sur VSCode. Puis, tapez le slug de la page que vous cherchez. Par exemple defining-routes

Pourquoi ne pas utiliser un manifeste ?

Nous avons envisagé d'utiliser un fichier manifeste (une autre façon populaire de générer la navigation des docs), mais nous avons constaté qu'un manifeste se désynchroniserait rapidement avec les fichiers. Le routage par système de fichiers nous oblige à réfléchir à la structure des docs et semble plus natif à Next.js.

Métadonnées

Chaque page a un bloc de métadonnées en haut du fichier séparé par trois tirets.

Champs obligatoires

Les champs suivants sont obligatoires :

---
title: Titre de la page
description: Description de la page
---

Il est recommandé de limiter le titre de la page à 2-3 mots (par exemple "Optimisation des images") et la description à 1-2 phrases (par exemple "Apprenez comment optimiser les images dans Next.js").

Champs optionnels

Les champs suivants sont optionnels :

---
nav_title: Titre de l'élément de navigation
source: app/building-your-application/optimizing/images
related:
  description: Voir la référence API du composant Image.
  links:
    - app/api-reference/components/image
---

Docs App et Pages

Puisque la plupart des fonctionnalités du Routeur App et du Routeur Pages sont complètement différentes, leurs docs pour chacun sont conservés dans des sections séparées (02-app et 03-pages). Cependant, il y a quelques fonctionnalités qui sont partagées entre eux.

Pages partagées

Pour éviter la duplication de contenu et le risque que le contenu se désynchronise, nous utilisons le champ source pour récupérer le contenu d'une page dans une autre. Par exemple, le composant <Link> se comporte principalement de la même manière dans App et Pages. Au lieu de dupliquer le contenu, nous pouvons récupérer le contenu de app/.../link.mdx dans pages/.../link.mdx :

---
title: <Link>
description: Référence API pour le composant <Link>.
---

Cette référence API vous aidera à comprendre comment utiliser les props
et options de configuration disponibles pour le composant Link.

---
title: <Link>
description: Référence API pour le composant <Link>.
source: app/api-reference/components/link
---

{/* NE PAS ÉDITER CETTE PAGE. */}
{/* Le contenu de cette page est récupéré depuis la source ci-dessus. */}

Nous pouvons donc éditer le contenu à un seul endroit et qu'il soit reflété dans les deux sections.

Contenu partagé

Dans les pages partagées, il peut parfois y avoir du contenu qui est spécifique au Routeur App ou au Routeur Pages. Par exemple, le composant <Link> a une prop shallow qui est seulement disponible dans Pages mais pas dans App.

Pour s'assurer que le contenu n'apparaît que dans le bon routeur, nous pouvons encapsuler des blocs de contenu dans des composants <AppOnly> ou <PagesOnly> :

Ce contenu est partagé entre App et Pages.

<PagesOnly>

Ce contenu ne sera affiché que dans les docs Pages.

</PagesOnly>

Ce contenu est partagé entre App et Pages.

Vous utiliserez probablement ces composants pour les exemples et blocs de code.

Blocs de code

Les blocs de code doivent contenir un exemple minimal fonctionnel qui peut être copié et collé. Cela signifie que le code doit pouvoir s'exécuter sans configuration supplémentaire.

Par exemple, si vous montrez comment utiliser le composant <Link>, vous devriez inclure l'instruction import et le composant <Link> lui-même.

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">À propos</Link>
}

Toujours exécuter les exemples localement avant de les commiter. Cela garantira que le code est à jour et fonctionnel.

Langage et nom de fichier

Les blocs de code doivent avoir un en-tête qui inclut le langage et le filename. Ajoutez une prop filename pour afficher une icône Terminal spéciale qui aide les utilisateurs à savoir où entrer la commande. Par exemple :

```bash filename="Terminal"
npx create-next-app
```

La plupart des exemples dans les docs sont écrits en tsx et jsx, et quelques-uns en bash. Cependant, vous pouvez utiliser n'importe quel langage supporté, voici la liste complète.

Quand vous écrivez des blocs de code JavaScript, nous utilisons les combinaisons de langage et extension suivantes.

Sélecteur TS et JS

Ajoutez un sélecteur de langage pour basculer entre TypeScript et JavaScript. Les blocs de code doivent être en TypeScript en premier avec une version JavaScript pour accommoder les utilisateurs.

Actuellement, nous écrivons les exemples TS et JS l'un après l'autre, et les lions avec la prop switcher :

```tsx filename="app/page.tsx" switcher

```

```jsx filename="app/page.js" switcher

```

Bon à savoir : Nous prévoyons de compiler automatiquement les extraits TypeScript en JavaScript dans le futur. En attendant, vous pouvez utiliser transform.tools.

Mise en évidence de lignes

Les lignes de code peuvent être mises en évidence. C'est utile quand vous voulez attirer l'attention sur une partie spécifique du code. Vous pouvez mettre en évidence des lignes en passant un nombre à la prop highlight.

Ligne unique : highlight={1}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">À propos</Link>
}

Lignes multiples : highlight={1,3}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">À propos</Link>
}

Plage de lignes : highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">À propos</Link>
}

Icônes

Les icônes suivantes sont disponibles pour utilisation dans les docs :

<Check size={18} />
<Cross size={18} />

Résultat :

Nous n'utilisons pas d'émojis dans les docs.

Notes

Pour les informations importantes mais non critiques, utilisez des notes. Les notes sont un bon moyen d'ajouter des informations sans distraire l'utilisateur du contenu principal.

> **Bon à savoir** : Ceci est une note sur une seule ligne.

> **Bon à savoir** :
>
> - Nous utilisons aussi ce format pour les notes multi-lignes.
> - Il y a parfois plusieurs éléments à connaître ou garder en tête.

Résultat :

Bon à savoir : Ceci est une note sur une seule ligne.

Bon à savoir :

• Nous utilisons aussi ce format pour les notes multi-lignes.
• Il y a parfois plusieurs éléments à connaître ou garder en tête.

Liens connexes

Les liens connexes guident le parcours d'apprentissage de l'utilisateur en ajoutant des liens vers les prochaines étapes logiques.

• Les liens seront affichés sous forme de cartes sous le contenu principal de la page.
• Les liens seront automatiquement générés pour les pages qui ont des pages enfants. Par exemple, la section Optimisation a des liens vers toutes ses pages enfants.

Créez des liens connexes en utilisant le champ related dans les métadonnées de la page.

---
related:
  description: Apprenez comment démarrer rapidement avec votre première application.
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

Champs imbriqués

Diagrammes

Les diagrammes sont un excellent moyen d'expliquer des concepts complexes. Nous utilisons Figma pour créer des diagrammes, suivant le guide de design de Vercel.

Les diagrammes vivent actuellement dans le dossier /public de notre site Next.js privé. Si vous souhaitez mettre à jour ou ajouter un diagramme, veuillez ouvrir une issue GitHub avec vos idées.

Composants personnalisés et HTML

Voici les composants React disponibles pour les docs : <Image /> (next/image), <PagesOnly />, <AppOnly />, <Cross />, et <Check />. Nous n'autorisons pas le HTML brut dans les docs à part la balise <details>.

Si vous avez des idées pour de nouveaux composants, veuillez ouvrir une issue GitHub.

Guide de style

Cette section contient des directives pour écrire des docs pour ceux qui sont nouveaux dans l'écriture technique.

Modèles de page

Bien que nous n'ayons pas de modèle strict pour les pages, il y a des sections de page que vous verrez répétées dans les docs :

• Aperçu : Le premier paragraphe d'une page devrait dire à l'utilisateur ce qu'est la fonctionnalité et à quoi elle sert. Suivi d'un exemple minimal fonctionnel ou de sa référence API.
• Convention : Si la fonctionnalité a une convention, elle devrait être expliquée ici.
• Exemples : Montrez comment la fonctionnalité peut être utilisée avec différents cas d'utilisation.
• Tableaux API : Les pages API devraient avoir un tableau d'aperçu à la fin de la page avec des liens de saut de section (quand possible).
• Prochaines étapes (Liens connexes) : Ajoutez des liens vers des pages connexes pour guider le parcours d'apprentissage de l'utilisateur.

N'hésitez pas à ajouter ces sections selon les besoins.

Types de pages

Les pages de documentation sont également divisées en deux catégories : Conceptuelles et Référence.

• Pages conceptuelles servent à expliquer un concept ou une fonctionnalité. Elles sont généralement plus longues et contiennent plus d'informations que les pages de référence. Dans la documentation Next.js, les pages conceptuelles se trouvent dans la section Construire votre application.
• Pages de référence servent à expliquer une API spécifique. Elles sont généralement plus courtes et plus ciblées. Dans la documentation Next.js, les pages de référence se trouvent dans la section Référence API.

Bon à savoir : Selon la page à laquelle vous contribuez, vous devrez peut-être adopter un ton et un style différents. Par exemple, les pages conceptuelles sont plus pédagogiques et utilisent le mot vous pour s'adresser à l'utilisateur. Les pages de référence sont plus techniques, elles utilisent des mots plus impératifs comme "créer, mettre à jour, accepter" et ont tendance à omettre le mot vous.

Ton

Voici quelques directives pour maintenir un style et un ton cohérents dans la documentation :

• Écrivez des phrases claires et concises. Évitez les digressions.
  • Si vous utilisez beaucoup de virgules, envisagez de diviser la phrase en plusieurs phrases ou d'utiliser une liste.
  • Remplacez les mots complexes par des mots plus simples. Par exemple, utiliser au lieu de employer.
• Soyez attentif au mot ceci. Il peut être ambigu et source de confusion, n'hésitez pas à répéter le sujet de la phrase si ce n'est pas clair.
  • Par exemple, Next.js utilise React au lieu de Next.js utilise ceci.
• Utilisez une voix active plutôt que passive. Une phrase active est plus facile à lire.
  • Par exemple, Next.js utilise React au lieu de React est utilisé par Next.js. Si vous utilisez des mots comme était et par, vous utilisez peut-être une voix passive.
• Évitez d'utiliser des mots comme facile, rapide, simple, juste, etc. Ces termes sont subjectifs et peuvent décourager les utilisateurs.
• Évitez les mots négatifs comme ne pas, impossible, ne veut pas, etc. Cela peut décourager les lecteurs.
  • Par exemple, "Vous pouvez utiliser le composant Link pour créer des liens entre les pages" au lieu de "N'utilisez pas la balise <a> pour créer des liens entre les pages".
• Écrivez à la deuxième personne (vous/votre). C'est plus personnel et engageant.
• Utilisez un langage neutre en termes de genre. Utilisez développeurs, utilisateurs ou lecteurs pour vous adresser au public.
• Si vous ajoutez des exemples de code, assurez-vous qu'ils sont correctement formatés et fonctionnels.

Bien que ces directives ne soient pas exhaustives, elles devraient vous aider à démarrer. Si vous souhaitez approfondir l'écriture technique, consultez le Cours d'écriture technique de Google.

Merci de contribuer à la documentation et de faire partie de la communauté Next.js !