Guide de contribution à la documentation

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

Cette page fournit des instructions sur la manière de 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 documents.

Pourquoi contribuer ?

Le travail open-source n'est jamais terminé, et la documentation non plus. Contribuer à la documentation est un excellent moyen pour les débutants de s'impliquer dans l'open-source et pour les développeurs expérimentés de clarifier des sujets plus complexes tout en partageant leurs connaissances avec la communauté.

En contribuant à la documentation de 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 remarqué l'absence d'un sujet particulier, vos contributions sont les bienvenues et appréciées.

Comment contribuer

Le contenu de la documentation se trouve dans le dépôt Next.js. Pour contribuer, vous pouvez modifier 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 vous recommandons de lire le Guide Open Source de GitHub pour apprendre comment forker un dépôt, créer une branche et soumettre une pull request.

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

Écrire en MDX

La documentation est écrite en MDX, un format markdown qui prend en charge la syntaxe JSX. Cela nous permet d'intégrer des composants React dans la documentation. Consultez le Guide Markdown de GitHub pour un aperçu rapide de la syntaxe markdown.

VSCode

Prévisualiser les modifications localement

VSCode dispose d'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).

Ensuite, 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 également les extensions suivantes pour les utilisateurs de VSCode :

• MDX : Intellisense et coloration syntaxique pour MDX.
• Prettier : Formater les fichiers MDX lors de la sauvegarde.

Processus de revue

Une fois que vous avez soumis votre contribution, les équipes Next.js ou Developer Experience examineront vos modifications, fourniront des commentaires 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'une assistance supplémentaire dans les commentaires de votre PR. Merci de contribuer à la documentation de 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

La documentation utilise le routage par système de fichiers. Chaque dossier et fichier à l'intérieur de /docs représente un segment de route. Ces segments sont utilisés pour générer les chemins d'URL, 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 par ordre alphabétique. Cependant, nous pouvons changer l'ordre des éléments en ajoutant un nombre à deux chiffres (00-) devant le nom du dossier ou du fichier.

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

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.mdx
└── ...

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

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

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

Pourquoi ne pas utiliser un manifeste ?

Nous avons envisagé d'utiliser un fichier manifeste (une autre méthode populaire pour générer la navigation de la documentation), 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 de la documentation et semble plus naturel pour 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
version: experimental
---

Documentation App et Pages

Étant donné que la plupart des fonctionnalités du Routeur App et du Routeur Pages sont complètement différentes, leur documentation est conservée dans des sections séparées (02-app et 03-pages). Cependant, il existe quelques fonctionnalités qui sont partagées entre elles.

Pages partagées

Pour éviter la duplication de contenu et le risque que le contenu devienne désynchronisé, 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 les 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 MODIFIER CETTE PAGE. */}
{/* Le contenu de cette page est récupéré depuis la source ci-dessus. */}

Nous pouvons ainsi modifier le contenu à un seul endroit et le voir 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 n'est disponible que dans Pages mais pas dans App.

Pour s'assurer que le contenu n'apparaît que dans le bon routeur, nous pouvons envelopper les 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 la documentation Pages.

</PagesOnly>

Ce contenu est partagé entre App et Pages.

Vous utiliserez probablement ces composants pour les exemples et les 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 devez inclure l'instruction import et le composant <Link> lui-même.

import Link from 'next/link'

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

Toujours exécuter les exemples localement avant de les commettre. 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ù saisir la commande. Par exemple :

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

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

Lors de l'écriture de blocs de code JavaScript, nous utilisons les combinaisons de langage et d'extension suivantes.

Bon à savoir :

• Assurez-vous d'utiliser l'extension js avec du code JSX dans les fichiers JavaScript.
• Par exemple, ```jsx filename="app/layout.js"

Sélecteur TS et JS

Ajoutez un sélecteur de langage pour basculer entre TypeScript et JavaScript. Les blocs de code doivent être d'abord en TypeScript 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 à l'avenir. En attendant, vous pouvez utiliser transform.tools.

Mise en évidence des lignes

Les lignes de code peuvent être mises en évidence. C'est utile lorsque 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">About</Link>
}

Plusieurs lignes : highlight={1,3}

import Link from 'next/link'

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

Plage de lignes : highlight={1-5}

import Link from 'next/link'

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

Icônes

Les icônes suivantes sont disponibles pour une utilisation dans la documentation :

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

Sortie :

Nous n'utilisons pas d'émojis dans la documentation.

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 également ce format pour les notes sur plusieurs lignes.
> - Il y a parfois plusieurs éléments à connaître ou à garder à l'esprit.

Sortie :

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

Bon à savoir :

• Nous utilisons également ce format pour les notes sur plusieurs lignes.
• Il y a parfois plusieurs éléments à connaître ou à garder à l'esprit.

Liens connexes

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

• Les liens seront affichés sous forme de cartes sous le contenu principal de la page.
• Les liens seront générés automatiquement pour les pages qui ont des 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, en suivant le guide de conception de Vercel.

Les diagrammes se trouvent 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 la documentation : <Image /> (next/image), <PagesOnly />, <AppOnly />, <Cross />, et <Check />. Nous n'autorisons pas le HTML brut dans la documentation à 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 rédiger de la documentation pour ceux qui sont nouveaux dans la rédaction 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 la documentation :

• Aperçu : Le premier paragraphe d'une page doit indiquer à 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 doit être expliquée ici.
• Exemples : Montrez comment la fonctionnalité peut être utilisée avec différents cas d'utilisation.
• Tableaux API : Les pages API doivent avoir un tableau récapitulatif en bas de la page avec des liens de saut vers les sections (quand c'est possible).
• Étapes suivantes (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 si nécessaire.

Types de pages

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

• Conceptuelles : Ces pages 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.
• Référence : Ces pages 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 et style

Voici quelques directives pour maintenir un ton et un style 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 à l'utilisation du mot ceci. Il peut être ambigu et source de confusion, n'hésitez pas à répéter le sujet de la phrase si nécessaire.
  • 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 les 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 pas vouloir, 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 vos connaissances en rédaction technique, consultez le Cours de rédaction technique de Google.

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