Beitragsrichtlinen 1.21.8

Richtlinien zur Beitragserstellung für die Fabric-Dokumentation

WARNING

Diese Seite ist für die Version 1.21.8 geschrieben. Dokumentationen für ältere Versionen sind möglicherweise unvollständig.

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 hier 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. locally Ä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. eine Seite im Ordner /players mit der Seite installing-fabric aus /players/installing-fabric.md zu verknüpfen, musst du Folgendes tun:
2. Erstelle bei deinem Fork ein neues Branch
3. Mache deine Änderung bei diesem Branch
4. Öffne einen Pull Request bei dem ursprünglichen Repository

Du kannst hier mehr über den GitHub-Ablauf lesen.

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

Deinen Fork klonen

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+ installieren.

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

npm install

Den Developmentserver ausführen

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

npm run dev

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

Die Website bauen

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

npm run build

Vorschau der gebauten Website

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

npm run 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 Label stage:expansion zu deinem Pull Request hinzufügen, zusammen mit einem Kommentar, der erklärt, was du deren Meinung nach erweitern könnten. 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 alle 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 Label framework gekennzeichnet.

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

INFO

Hinweis: Das Ändern von Seitenleistendateien und der Konfiguration der Navigationsleiste zählt nicht als Pull-Request für das Framework.

Stilrichtlinien

Wenn du unsicher bist, kannst du im Fabric Discord oder über GitHub Diskussionen 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 Titel und eine Beschreibung 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
---

Füge Anker zu den Überschriften hinzu

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 /reference Mods platzieren

Wenn du Seiten erstellst oder änderst, die Code enthalten, platziere den Code an einer geeigneten Stelle innerhalb des Referenz-Mod (im Ordner /reference des Repository). Verwende dann die Code-Snippet-Funktion, die von VitePress angeboten wird, um den Code einzubetten, oder wenn du eine größere Kontrollspanne benötigst, kannst du die transclude-Funktion von markdown-it-vuepress-code-snippet-enhanced verwenden.

Dies wird die Zeilen 15-21 der Datei FabricDocsReference.java des Referenz-Mod einbetten.

md

<<< @/reference/1.21.8/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.core.Registry;
import net.minecraft.core.component.DataComponents;
import net.minecraft.core.particles.SimpleParticleType;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.resources.ResourceLocation;

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

import com.example.docs.component.ModComponents;

//#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(BuiltInRegistries.PARTICLE_TYPE, ResourceLocation.fromNamespaceAndPath(MOD_ID, "sparkle_particle"), SPARKLE_PARTICLE);
		//#particle_register_main
		//#entrypoint

		// #tooltip_provider
		ComponentTooltipAppenderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		// #tooltip_provider
	}
}

Nur der Code zwischen den #test_transclude-Tags wird eingebettet.

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

md

@[code transcludeWith=#entrypoint](@/reference/1.21.8/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!");

		// #tooltip_provider
		ComponentTooltipAppenderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		// #tooltip_provider
	}
}

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 config.mts hinzufügen.

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

Anleitung zur Erweiterung

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 /assets abgelegt werden.

Nutze 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 nicht die Dateierweiterung 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)