Beitragsrichtlinen 26.2

Richtlinien zur Beitragserstellung für die Fabric-Dokumentation

Diese Website nutzt VitePress um statisches HTML von den verschiedenen Markdown-Dateien zu generrieren. Du solltest dich mit den Markdown-Erweiterungen vertraut machen, die VitePress unterstützt.

Du hast drei Möglichkeiten, zu dieser Website beizutragen:

• Übersetzen der Dokumentation
• Inhalte beitragen
• Zum Framework beitragen

Alle Beiträge müssen unseren Stilrichtlinien entsprechen.

Übersetzen der Dokumentation

Falls du die Dokumentation in deine Sprache übersetzen möchtest, kannst du dies auf der Fabric Crowdin-Seite tun.

new-content Inhalt beitragen

Inhaltliche Beiträge sind die wichtigste Möglichkeit, zur Fabric-Dokumentation beizutragen.

Alle Inhaltsbeiträge durchlaufen die folgenden Stufen, die jeweils mit einem Label versehen sind:

1. lokal Änderungen vorbereiten und einen Pull Request pushen
2. stage:expansion: Anleitung zur Erweiterung, falls erforderlich
3. stage:verification: Verifikation des Inhalts
4. stage:cleanup: Grammatik, Linting...
5. stage:ready: Bereit zum mergen!

Alle Inhalte sollten unseren Stilrichtlinien entsprechen.

1. Deine Änderungen vorbereiten

Diese Website ist OpenSource und wird in einem GitHub-Repository entwickelt, was bedeutet, dass wir uns auf den GitHub-Ablauf verlassen:

1. Forke das GitHub Repository
2. Erstelle bei deinem Fork ein neues Branch
3. Mache deine Änderung in diesem Branch
4. Öffne einen Pull Request bei dem ursprünglichen Repository

Du kannst mehr über den Github Ablauf.

Du kannst Änderungen entweder durch die Weboberfläche von GitHub machen oder du kannst die Website lokal entwickeln und die Vorschau ansehen.

Klonen deines Fork

Wenn du lokal entwickeln willst, musst du Git installieren.

Danach klone deinen Fork des Repository mit:

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

Abhängigkeiten installieren

Wenn du deine Änderungen lokal ansehen möchtest, musst du Node.js 18+ oder pnpm installieren.

Danach stelle sicher, dass du alle Abhängigkeiten installierst:

pnpm install

Ausführen des Entwicklungsserver

Damit kannst du deine Änderungen lokal auf localhost:3000 ansehen und die Seite wird automatisch neu geladen, wenn du Änderungen vornimmst.

pnpm dev

Jetzt kannst du die Website über den Browser öffnen und durchsuchen, indem du http://localhost:5173 aufrufst.

Bauen der Website

Dies wird alle Markdown-Dateien in statische HTML-Dateien kompilieren und diese in .vitepress/dist ablegen:

pnpm build

Vorschau der gebauten Website

Dies wird einen lokalen Server auf dem Port 3000 starten, der den Inhalt in .vitepress/dist bereitstellt:

pnpm preview

Einen Pull Request öffnen

Wenn du mit deinen Änderungen zufrieden bist, kannst du sie pushen:

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

Folge dann dem Link in der Ausgabe von git push, um einen PR zu öffnen.

2. stage:expansion Anleitung zur Erweiterung, falls erforderlich

Wenn das Dokumentationsteam der Meinung ist, dass du deinen Pull Request erweitern könntest, wird ein Mitglied des Teams das Kennzeichen stage:expansion zu deinem Pull Request hinzufügen, zusammen mit einem Kommentar, der erklärt, was du deren Meinung nach erweitern könntest. Wenn du mit dem Vorschlag einverstanden bist, kannst du deinen Pull Request erweitern.

Wenn du deinen Pull Request nicht erweitern willst, aber gerne möchtest, dass jemand anderes ihn zu einem späteren Zeitpunkt erweitert, solltest du ein Issue auf der Issues Seite erstellen und erklären, was deiner Meinung nach erweitert werden könnte. Das Dokumentationsteam fügt dann das Label help-wanted zu deinem PR hinzu.

3. stage:verification Verifikation des Inhalts

Dies ist die wichtigste Phase, da sie sicherstellt, dass der Inhalt korrekt ist und den Stilrichtlinien der Fabric Documentation entspricht.

In dieser Phase sollten die folgenden Fragen beantwortet werden:

• Ist der ganze Inhalt korrekt?
• Ist der ganze Inhalt aktuell?
• Deckt der Inhalt alle Fälle ab, z. B. verschiedene Betriebssysteme?

4. stage:cleanup Aufräumen

In dieser Phase passiert folgendes:

• Beheben aller Grammatikfehler mit LanguageTool
• Linten aller Markdown-Dateien mit markdownlint
• Formatierung des ganzen Java-Code mit Checkstyle
• Andere verschiedene Korrekturen oder Verbesserungen

framework Zum Framework beitragen

Framework bezieht sich auf die interne Struktur der Website. Alle Pull Requests, die das Framework der Website verändern, werden mit dem Kennzeichen framework gekennzeichnet.

Du solltest wirklich nur Pull Requests für das Framework öffnen, nachdem du dich mit dem Dokumentationsteam auf dem Fabric Discord oder über ein Issue ausgetauscht hast.

INFO

Ändern von Dateien der Seitenleiste und der Konfiguration der Navigationsleiste gilt nicht als Framework Pull Request.

Stilrichtlinien

Wenn du über etwas unsicher bist, kannst du auf dem Fabric Discord oder über GitHub Discussions nachfragen.

Schreibe das Original in amerikanischem Englisch

Die ganze originale Dokumentation ist in englischer Sprache verfasst und folgt den amerikanischen Grammatikregeln.

Daten zum Frontmatter hinzufügen

Alle Seiten müssen einen title und eine description im Frontmatter haben.

Vergiss nicht, auch deinen GitHub-Benutzernamen zu authors im Frontmatter der Markdown-Datei hinzuzufügen! Auf diese Weise können wir dir angemessene Anerkennung geben.

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

Anker zu Überschriften hinzufügen

Jede Überschrift muss einen Anker haben, der als Link zu dieser Überschrift dient:

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

Der Anker muss Kleinbuchstaben, Zahlen und Bindestriche enthalten.

Code innerhalb des Beispiel-Mods platzieren

Wenn du Seiten erstellst oder änderst, die Code enthalten, platziere den Code an einer geeigneten Stelle innerhalb des Beispiel-Mod (im Ordner /reference des Repository). Verwende dann die Code-Snippet-Funktion von VitePress, um den Code einzubetten.

Um beispielsweise die Zeilen 15 bis 21 der Datei ExampleMod.java aus dem Mod hervorzuheben:

md

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

java

package com.example.docs;

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

import net.minecraft.core.Registry;
import net.minecraft.core.component.DataComponents;
import net.minecraft.core.particles.SimpleParticleType;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.resources.Identifier;
import net.minecraft.tags.BiomeTags;
import net.minecraft.world.level.levelgen.GenerationStep;

import net.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.biome.v1.BiomeModifications;
import net.fabricmc.fabric.api.biome.v1.BiomeSelectors;
import net.fabricmc.fabric.api.item.v1.ItemComponentTooltipProviderRegistry;
import net.fabricmc.fabric.api.particle.v1.FabricParticleTypes;

import com.example.docs.component.ModComponents;
import com.example.docs.worldgen.ExampleModWorldPlacedFeatures;

public class ExampleMod 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 = "example-mod";
	public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

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

	@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!");

		// Register our custom particle type in the mod initializer.
		Registry.register(BuiltInRegistries.PARTICLE_TYPE, Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "sparkle_particle"), SPARKLE_PARTICLE);
		// Spawns everywhere in the overworld
		BiomeModifications.addFeature(
				BiomeSelectors.foundInOverworld(),
				GenerationStep.Decoration.UNDERGROUND_ORES,
				ExampleModWorldPlacedFeatures.DIAMOND_BLOCK_ORE_PLACED_KEY
		);

		// Spawns in forest biomes only
		BiomeModifications.addFeature(
				BiomeSelectors.tag(BiomeTags.IS_FOREST),
				GenerationStep.Decoration.VEGETAL_DECORATION,
				ExampleModWorldPlacedFeatures.DIAMOND_TREE_PLACED_KEY
		);

		ItemComponentTooltipProviderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		ItemComponentTooltipProviderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.ADVANCED_CUSTOM_COMPONENT);
	}
}

Wenn du einen größeren Kontrollbereich benötigst, kannst du die Transclude-Funktion von markdown-it-vuepress-code-snippet-enhanced verwenden.

So werden beispielsweise die Abschnitte der obigen Datei eingebettet, die mit dem Tag #entrypoint gekennzeichnet sind:

md

<<< @/reference/latest/src/main/java/com/example/docs/ExampleMod.java#entrypoint

ExampleMod.java

public class ExampleMod 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 = "example-mod";
	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!");
	}
}

Erstelle eine Seitenleiste für jeden neuen Abschnitt

Wenn du einen neuen Abschnitt erstellst, solltest du eine neue Seitenleiste im Ordner .vitepress/sidebars anlegen und sie zur Datei i18n.mts hinzufügen.

Wenn du dabei Hilfe benötigst, frage bitte auf dem Fabric Discord im Kanal #docs nach.

Füge neue Seiten zu den relevanten Seitenleisten hinzu

Wenn du eine neue Seite erstellst, solltest du sie der entsprechenden Seitenleiste im Ordner .vitepress/sidebars hinzufügen.

Auch hier gilt: Wenn du Hilfe benötigst, frage auf dem Fabric Discord im Kanal #docs nach.

Platziere Medien in /assets

Alle Bilder sollten an einem geeigneten Ort im Ordner /public/assets abgelegt werden.

Verwende relative Links!

Der Grund dafür ist das vorhandene Versionssystem, das die Links verarbeitet, um die Version vorher hinzuzufügen. Wenn du absolute Links verwendest, wird die Versionsnummer nicht zum Link hinzugefügt.

Du darfst auch die Dateierweiterung nicht zu dem Link hinzufügen.

Um zum Beispiel von der Seite /players/index.md auf die Seite /develop/index.md zu verlinken, musst du folgendes tun:

✅ 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)