Lignes directrices pour les contributions

Ce site utilise VitePress pour générer du HTML statique à partir de divers fichiers Markdown. Vous devriez vous familiariser avec les extensions Markdown que VitePress supporte ici.

Il y a trois façons de contribuer à ce site web :

• Traduire la documentation
• Contribuer au contenu
• Contribuer au framework

Toutes les contributions doivent suivre nos lignes directrices de style.

Traduire la documentation

Si vous souhaitez traduire la documentation dans votre langue, vous pouvez le faire sur la page Crowdin de Fabric.

new-content Contribuer au contenu

Les contributions de contenu sont le principal moyen de contribuer à la documentation de Fabric.

Toutes les contributions de contenu passent par les étapes suivantes, chacune étant associée à une étiquette :

1. locally Préparez vos modifications et soumettez une PR
2. stage:expansion: Guide pour l'expansion si nécessaire
3. stage:verification: Vérification du contenu
4. stage:cleanup: Grammaire, Linting...
5. stage:ready: Prêt à être fusionné !

Tout le contenu doit suivre nos lignes directrices de style.

1. Préparez vos modifications

Ce site est open-source et est développé dans un dépôt GitHub, ce qui signifie que nous nous appuyons sur le flux GitHub :

1. Forkez le dépôt Github
2. Créez une nouvelle branche sur votre fork
3. Effectuez vos modifications sur cette branche
4. Ouvrez une Pull Request vers le dépôt original

Vous pouvez en savoir plus sur le flux GitHub ici.

Vous pouvez soit apporter des modifications depuis l'interface web de GitHub, soit développer et prévisualiser le site localement.

Cloner votre fork

Si vous souhaitez développer localement, vous devrez installer Git.

Ensuite, clonez votre fork du dépôt avec :

# make sure to replace "your-username" with your actual username
git clone https://github.com/your-username/fabric-docs.git

Installer les dépendances

Si vous souhaitez prévisualiser vos modifications localement, vous devrez installer Node.js 18+.

Ensuite, assurez-vous d'installer toutes les dépendances avec :

npm install

Exécuter le serveur de développement

Cela vous permettra de prévisualiser vos modifications localement à l'adresse localhost:5173 et rechargera automatiquement la page lorsque vous apporterez des modifications.

npm run dev

Vous pouvez maintenant ouvrir et parcourir le site web depuis le navigateur en visitant http://localhost:5173.

Construire le site web

Cela va compiler tous les fichiers Markdown en fichiers HTML statiques et les placer dans .vitepress/dist :

npm run build

Prévisualiser le site web construit

Cela va démarrer un serveur local sur le port 4173 servant le contenu trouvé dans .vitepress/dist :

npm run preview

Ouvrir une Pull Request

Une fois que vous êtes satisfait de vos modifications, vous pouvez push vos modifications :

git add .
git commit -m "Description of your changes"
git push

Ensuite, suivez le lien dans la sortie de git push pour ouvrir une PR.

2. stage:expansion Guide pour l'expansion si nécessaire

Si l'équipe de documentation pense que vous pourriez développer votre pull request, un membre de l'équipe ajoutera l'étiquette stage:expansion à votre pull request avec un commentaire expliquant ce qu'ils pensent que vous pourriez développer. Si vous êtes d'accord avec la suggestion, vous pouvez développer votre pull request.

Si vous ne souhaitez pas développer votre pull request, mais que vous êtes d'accord pour que quelqu'un d'autre le fasse ultérieurement, vous devriez créer une issue sur la page des Issues et expliquer ce que vous pensez pouvoir être développé. L'équipe de documentation ajoutera alors l'étiquette help-wanted à votre PR.

3. stage:verification Vérification du contenu

C'est l'étape la plus importante car elle garantit que le contenu est exact et suit le guide de style de la documentation Fabric.

À cette étape, les questions suivantes doivent être répondues :

• Tout le contenu est-il correct ?
• Tout le contenu est-il à jour ?
• Le contenu couvre-t-il tous les cas, comme les différents systèmes d'exploitation ?

4. stage:cleanup Nettoyage

À cette étape, les actions suivantes sont effectuées :

• Correction des problèmes de grammaire à l'aide de LanguageTool
• Vérification de tous les fichiers Markdown à l'aide de markdownlint
• Formatage de tout le code Java à l'aide de Checkstyle
• Autres corrections ou améliorations diverses

framework Contribuer au Framework

Le framework fait référence à la structure interne du site web. Toute pull request modifiant le framework du site web sera étiquetée avec l'étiquette framework.

Vous devriez vraiment ne faire des pull requests de framework qu'après avoir consulté l'équipe de documentation sur le Discord de Fabric ou via une issue.

INFO

La modification des fichiers de la barre latérale et de la configuration de la barre de navigation ne compte pas comme une pull request de framework.

Lignes directrices de style

Si vous avez des doutes sur quoi que ce soit, vous pouvez poser vos questions sur le Discord de Fabric ou via les Discussions GitHub.

Écrire l'original en anglais américain

Toute la documentation originale est rédigée en anglais, en suivant les règles de grammaire américaines.

Ajouter des données au Frontmatter

Chaque page doit avoir un title et une description dans le frontmatter.

N'oubliez pas d'ajouter également votre nom d'utilisateur GitHub à authors dans le frontmatter du fichier Markdown ! De cette manière, nous pouvons vous attribuer le mérite qui vous revient.

---
title: Title of the Page
description: This is the description of the page.
authors:
  - your-username
---

# Title of the Page {#title-of-the-page}

...

Ajouter des ancres aux titres

Chaque titre doit avoir une ancre, qui est utilisée pour créer un lien vers ce titre :

# This Is a Heading {#this-is-a-heading}

L'ancre doit utiliser des caractères en minuscules, des chiffres et des tirets.

Placer le code dans le mod /reference

Si vous créez ou modifiez des pages contenant du code, placez le code à un emplacement approprié dans le mod de référence (situé dans le dossier /reference du dépôt). Ensuite, utilisez la fonctionnalité d'extrait de code offerte par VitePress pour intégrer le code.

Par exemple, pour mettre en évidence les lignes 15-21 du fichier FabricDocsReference.java du mod de référence :

md

<<< @/reference/latest/src/main/java/com/example/docs/FabricDocsReference.java{15-21}

java

package com.example.docs;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import net.minecraft.particle.SimpleParticleType;
import net.minecraft.registry.Registries;
import net.minecraft.registry.Registry;
import net.minecraft.util.Identifier;

import net.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.particle.v1.FabricParticleTypes;

//#entrypoint
public class FabricDocsReference implements ModInitializer {
	// This logger is used to write text to the console and the log file.
	// It is considered best practice to use your mod id as the logger's name.
	// That way, it's clear which mod wrote info, warnings, and errors.
	public static final String MOD_ID = "fabric-docs-reference";
	public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

	//#entrypoint
	//#particle_register_main
	// This DefaultParticleType gets called when you want to use your particle in code.
	public static final SimpleParticleType SPARKLE_PARTICLE = FabricParticleTypes.simple();

	//#particle_register_main
	//#entrypoint
	@Override
	public void onInitialize() {
		// This code runs as soon as Minecraft is in a mod-load-ready state.
		// However, some things (like resources) may still be uninitialized.
		// Proceed with mild caution.

		LOGGER.info("Hello Fabric world!");
		//#entrypoint

		//#particle_register_main
		// Register our custom particle type in the mod initializer.
		Registry.register(Registries.PARTICLE_TYPE, Identifier.of(MOD_ID, "sparkle_particle"), SPARKLE_PARTICLE);
		//#particle_register_main
		//#entrypoint
	}
}

Si vous avez besoin d'un contrôle plus étendu, vous pouvez utiliser la fonctionnalité de transclusion de markdown-it-vuepress-code-snippet-enhanced.

Par exemple, ceci intégrera les sections du fichier ci-dessus qui sont marquées avec l'étiquette #entrypoint :

md

@[code transcludeWith=#entrypoint](@/reference/latest/src/main/java/com/example/docs/FabricDocsReference.java)

java

public class FabricDocsReference implements ModInitializer {
	// This logger is used to write text to the console and the log file.
	// It is considered best practice to use your mod id as the logger's name.
	// That way, it's clear which mod wrote info, warnings, and errors.
	public static final String MOD_ID = "fabric-docs-reference";
	public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

	@Override
	public void onInitialize() {
		// This code runs as soon as Minecraft is in a mod-load-ready state.
		// However, some things (like resources) may still be uninitialized.
		// Proceed with mild caution.

		LOGGER.info("Hello Fabric world!");
	}
}

Créer une barre latérale pour chaque nouvelle section

Si vous créez une nouvelle section, vous devez créer une nouvelle barre latérale dans le dossier .vitepress/sidebars et l'ajouter au fichier i18n.mts.

Si vous avez besoin d'aide, veuillez poser votre question dans le canal #docs du Discord de Fabric.

Ajouter de nouvelles pages aux barres latérales pertinentes

Lors de la création d'une nouvelle page, vous devez l'ajouter à la barre latérale pertinente dans le dossier .vitepress/sidebars.

Encore une fois, si vous avez besoin d'aide, demandez dans le canal #docs du Discord de Fabric.

Placer les médias dans /assets

Toutes les images doivent être placées à un endroit approprié dans le dossier /public/assets.

Utilisez des liens relatifs !

Cela est dû au système de versioning en place, qui traitera les liens pour ajouter la version au préalable. Si vous utilisez des liens absolus, le numéro de version ne sera pas ajouté au lien.

Vous ne devez pas non plus ajouter l'extension de fichier au lien.

Par exemple, pour créer un lien vers la page trouvée dans /players/index.md depuis la page /develop/index.md, vous devriez faire ce qui suit :

✅ Correct

This is a relative link!
[Page](../players/index)

❌ Wrong

This is an absolute link.
[Page](/players/index)

❌ Wrong

This relative link has the file extension.
[Page](../players/index.md)