Entwickler

Starte damit, die Dokumentation deines Projekts auf unserem Wiki zu hosten!

Diese Anleitung enthält Informationen zur lokalen Entwicklung und zum Dokumentationsformat. Für eine Anleitung zum Veröffentlichen der Docs auf unserer Website, schaue bitte auf der Seite Veröffentlichen nach.

Voraussetzungen

Um mit dem Hosten der Dokumentation auf unserem Wiki zu beginnen, muss dein Projekt nur einige minimale Anforderungen erfüllen:

• Auf einem GitHub-Repository gehostet sein (sowohl private als auch öffentliche Repositories funktionieren!)
• Auf entweder Modrinth oder CurseForge genehmigt sein
• Das GitHub-Repository muss als URL des Quellcodes des Projekts auf der jeweiligen Hosting-Website verlinkt sein
  (dies ist derzeit erforderlich, um den Besitz des Projekts zu verifizieren)

Zusätzlich sollte die Person, die das Projekt im Wiki registriert, Maintain- oder Admin-Zugriff auf das GitHub-Repository haben.

Ordnerstruktur

Beginne damit, ein neues Verzeichnis in deinem Projekt zu erstellen. Dies kann sich an jedem beliebigen Pfad deiner Wahl befinden.
Zum Beispiel kannst du docs/(deine Mod-ID hier) oder einfach docs verwenden, beides ist gleichermaßen gültig.

Ein minimales Beispiel für eine Ordnerstruktur könnte so aussehen:

docs
├── blocks
│   ├── generator.mds
│   └── _meta.json
├── introduction.mdx
├── _meta.json
└── sinytra-wiki.json

docs
├── .assets
│   └── item
│       └── examplemod
│           └── generator.png
├── .translated
│   └── de_de
│       └── blocks
│           ├── generator.mdx
│           └── _meta.json
├── blocks
│   ├── generator.mds
│   └── _meta.json
├── introduction.mdx
├── _meta.json
└── sinytra-wiki.json

Lass uns darüber sprechen, was jede dieser Dateien macht:

• sinytra-wiki.json: Die Hauptmetadaten-Datei, das "Herz" des Dokumentationspakets, enthält Informationen über das Projekt. Das Format ihres Inhalts wird weiter unten ausführlich erklärt.
• _meta.json: Kann im Root-Ordner sowie in jedem Unterordner abgelegt werden. Bietet Anzeigennamen für Dateien und Ordner, die in der Navigationsleiste der Dokumentation auf dem Wiki angezeigt werden, und legt auch die Reihenfolge fest, in der sie angezeigt werden. Wenn keine bereitgestellt wird, werden Fallback-Anzeigennamen automatisch generiert.
• *.mdx-Dateien: Enthalten den Dokumentationsinhalt. Weitere Informationen zum MDX-Format findest du auf ihrer Website. Da MDX zu JavaScript kompiliert, gibt es bestimmte Einschränkungen, welche Komponenten und Tags zusätzlich zu Standard-Markdown verwendet werden können. Eine vollständige Beschreibung findest du weiter unten.

Assets

Assets werden verwendet, um Bilder von Items, Blöcken und anderen Projektinhalten auf der Website anzuzeigen. Diese können als Teil von Rezepten, Seitenleisteninformationen oder benutzerdefinierten Komponenten verwendet werden.

Assets werden mit Resource Locations identifiziert, die die gleiche Syntax wie im Spiel selbst verwenden. Es wird empfohlen, die Namen der Assets mit den In-Game-IDs der Objekte, zu denen sie gehören, abzugleichen.

Gerenderte Assets, einschließlich sowohl Items als auch Blöcken, sollten unter .assets/item/(modid) im Dokumentationsverzeichnis abgelegt werden, wobei modid der Namespace jeder Textur ist, die du bereitstellen möchtest.

Jedes Asset muss im .png-Format vorliegen. Der Name der Datei ist dir überlassen.

Beispiel: examplemod:generator würde auf (root)/.assets/item/examplemod/generator.png verweisen.

Übersetzung

Die Dokumentation kann in verschiedene Sprachen übersetzt werden, die vom Wiki unterstützt werden. Eine vollständige Liste findest du im Sprachauswahl-Dropdown, das sich im äußersten rechten Bereich der Navigationsleiste befindet.

Lokalisierte Dateien müssen unter .translated/(lang) im Dokumentationsverzeichnis abgelegt werden, wobei (lang) der gewünschte Sprachcode im (lang)_(region)-Format ist. Derzeit entsprechen alle Regionen der Sprache, sodass es ausreicht, den Sprachcode des Zielgebiets zu nehmen und die Region auf denselben Wert wie die Sprache zu setzen (z. B. deutsche Übersetzungen (de) würden unter .translated/de_de abgelegt werden).

Die lokale Ordnerstruktur folgt dem gleichen Layout wie das Root-Verzeichnis. Sowohl Dokumentationsinhaltsdateien (.mdx) als auch Ordner Metadaten (_meta.json) können übersetzt werden. Übersetzte Inhalte haben Vorrang vor der Standardsprache, wenn sie geladen werden. Nicht übersetzte Dateien werden jedoch auch angezeigt, wenn die Sprache nicht der Standard-Sprache entspricht. Daher wird empfohlen, alle Dateien zu übersetzen, wann immer möglich.

Benutzerdefinierte Startseite

Das Wiki bietet eine spezielle Landing-Page für die Dokumentation, die als "Projekt-Homepage" bezeichnet wird. Standardmäßig zeigt diese die Beschreibung des verlinkten Plattformprojekts.

Wenn du stattdessen eigene Inhalte bereitstellen möchtest, kannst du dies tun, indem du eine Datei _homepage.mdx im Root-Ordner deiner Dokumentation erstellst (auf derselben Ebene wie sinytra-wiki.json). Der Inhalt der Datei folgt dem gleichen Format wie reguläre Dokumentationsseiten, mit Ausnahme der Frontmatter-Metadaten (z. B. Titel), die ignoriert werden. Der Titel der Startseite wird immer dem Namen des Mods entsprechen, während die Seitenleiste verschiedene Informationen über das Plattformprojekt anzeigt, wie z. B. die Autoren des Projekts, Kategorien und verfügbare Minecraft-Versionen.

Dokumentationsformat

Wiki-Metadaten

Die Wiki-Metadaten-Datei gibt Identifikationsinformationen für das Projekt an, die notwendig sind, damit das Wiki das Projekt laden kann.

Sie muss in einer Datei namens sinytra-wiki.json im Root-Verzeichnis der Dokumentation abgelegt werden.

{
    "id": "mffs",
    "platform": "modrinth",
    "slug": "mffs"
}

Die Wiki-Metadaten-Datei enthält die folgenden Eigenschaften, die alle erforderlich sind:

• id: Eindeutige Projekt-ID, die verwendet wird, um das Projekt im Wiki zu identifizieren. Wir empfehlen, deine Mod-ID oder den Slug der Hosting-Plattform zu verwenden.
• platform: Die Hosting-Plattform deines Projekts. Kann entweder modrinth oder curseforge sein.
• slug: Der Projekt-Slug der Hosting-Plattform.

Der Projekt-Slug kann leicht aus der URL der Projektseite deines Projekts extrahiert werden, wie in den folgenden Beispielen gezeigt, wobei {slug} als Platzhalter für den tatsächlichen Wert dient.

• Für Modrinth-Projekte: https://modrinth.com/mod/{slug}
• Für CurseForge-Projekte: https://www.curseforge.com/minecraft/mc-mods/{slug}

Die JSON-Schema-Spezifikation für diese Datei findest du hier.

Ordner-Metadaten

Bietet zusätzliche Informationen für die Navigationsleiste der Dokumentationsseite:

• Die Anzeigennamen von Ordnern und Dateien. Wenn diese nicht angegeben werden, verwendet das Wiki automatisch generierte Anzeigennamen.
• Die Reihenfolge der Einträge in der Navigationsleiste. Standardmäßig werden Ordner zuerst angezeigt, gefolgt von regulären Dateien, alle alphabetisch sortiert.

Um mögliche unerwünschte Anzeigeprobleme zu vermeiden, empfehlen wir, immer vollständige Ordner-Metadaten in deiner Dokumentation bereitzustellen.

{
    "blocks": "Blocks",
    "items": "Completely custom name",
    "introduction.mdx": "Introduction"
}

Die Ordner-Metadaten im JSON-Format bestehen aus Schlüssel-Wert-Paaren, wobei die Schlüssel den Namen einer Datei oder eines Ordners darstellen und die Werte deren Anzeigennamen sind. Beim Angeben eines Dateinamens ist der vollständige Name einschließlich der Erweiterung erforderlich.

Ordner-Metadaten sind in einer Datei namens _meta.json enthalten und können innerhalb eines beliebigen Ordners im Dokumentationsverzeichnis abgelegt werden, einschließlich des Root-Verzeichnisses selbst (z. B. auf derselben Ebene wie sinytra-wiki.json).

Die JSON-Schema-Spezifikation für diese Datei findest du hier.

Icons

Du kannst Icons für jeden Metadaten-Eintrag hinzufügen, die in der Navigationsleiste angezeigt werden, indem du den Metawert in ein Objekt umwandelst und den Namen des Icons wie unten gezeigt angibst.

Der angegebene Icon-Name sollte ein Lucide-Icon Komponentenname (ohne das Suffix Icon) sein. Weitere Informationen zu Icon-Namen findest du auf der Seite Format.

{
    "blocks": {
        "name": "Blocks",
        "icon": "Box"
    }
}

Versionierung

Du kannst mehrere Versionen der Dokumentation deines Projekts im Wiki anzeigen, indem du eine versions-Eigenschaft zu deiner Dokumentations-Metadaten-Datei hinzufügst. Diese enthält eine Zuordnung von Minecraft-Versionen (die im Versionsauswähler sowie in den URL-Pfaden angezeigt werden) zu Git-Branch-Namen.

Die Ordnerstruktur der Dokumentation bleibt in allen Branches gleich, wobei die Inhalte pro Branch isoliert sind, einschließlich Assets und Lokalisierung. Dokumentations-Metadaten-Dateien (sinytra-wiki.json) aus anderen Branches werden ignoriert, da alle erforderlichen Informationen bereits in der Datei des Standard-Branches enthalten sind.

{
    ...
    "versions": {
        "1.19.2": "my-git-branch-name",
        "1.18.2": "another-branch"
    }
}

Gradle-Plugin

Wir bieten ein hervorragendes Wiki Gradle-Plugin, das dir beim Erstellen der Dokumentation hilft.

Die Funktionen umfassen:

• Lokale Echtzeitvorschau deiner Dokumentation, die genauso aussieht wie sie später im Wiki angezeigt wird
• Automatisches Erstellen von Asset-Rendern für Inventar-Modelle aller Mod-Items
• Neuvalidierung der Dokumentation nach der Veröffentlichung

Eine vollständige Anleitung zur Nutzung findest du im GitHub-Repository.

Nächste Schritte

➡️ Erkunde die Details des MDX Dokumentationsformats.