Wytyczne współtworzenia 26.1.2

Wytyczne dotyczące współtworzenia i wnoszenia wkładu do dokumentacji Fabric.

Ta strona używa VitePress do generowania statycznego HTML-a z różnych plików Markdown. Powinieneś zapoznać się z rozszerzeniami języka Markdown obsługiwanymi przez vitepress.

Istnieją trzy sposoby, w jakie możesz pomóc współtworzyć tę stronę:

• Tłumaczenie dokumentacji
• Współtworzenie treści
• Współtworzenie frameworka

Wszystkie współtworzone treści i wniesiony wkład muszą być zgodne z naszymi wytycznymi dotyczącymi stylu.

Tłumaczenie dokumentacji

Jeśli chcesz przetłumaczyć dokumentację na swój język, możesz to zrobić dołączając do projektu Fabric na platformie Crowdin.

new-content Współtworzenie treści

Głównym sposobem wniesienia wkładu do dokumentacji Fabric jest publikowanie treści.

Wszystkie treści przechodzą przez następujące etapy, z których każdy jest powiązany z etykietą:

1. locally Przygotuj zmiany i prześlij PR
2. stage:expansion: Wskazówki dotyczące rozbudowy, jeśli to konieczne
3. stage:verification: Weryfikacja treści
4. stage:cleanup: Gramatyka, sprawdzanie poprawności...
5. stage:ready: Gotowe do połączenia!

Cała treść musi być zgodna z naszymi wytycznymi dotyczącymi stylu.

1. Przygotuj zmiany

Ta strona internetowa jest oparta na otwartym kodzie źródłowym i jest rozwijana w repozytorium GitHub, co oznacza, że opieramy się na przepływie GitHub:

1. Fork repozytorium github
2. Utwórz nową gałąź na swoim forku
3. Wprowadź zmiany w tej gałęzi
4. Otwórz żądanie ściągnięcia do oryginalnego repozytorium

Możesz dowiedzieć się więcej o Przepływ GitHub.

Zmiany można wprowadzać za pośrednictwem internetowego interfejsu użytkownika w serwisie GitHub lub można opracować witrynę i wyświetlić jej podgląd lokalnie.

Klonowanie Twojego forka

Jeśli chcesz rozwijać się lokalnie, musisz zainstalować git.

Następnie sklonuj swój fork repozytorium za pomocą:

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

Instalowanie zależności

Jeśli chcesz wyświetlić podgląd zmian lokalnie, musisz zainstalować node.js 18+ i pnpm.

Następnie pamiętaj o zainstalowaniu wszystkich zależności za pomocą:

pnpm install

Uruchamianie serwera deweloperskiego

Umożliwi ci to podgląd zmian lokalnie na localhost:5173 i automatyczne przeładowanie strony po wprowadzeniu zmian.

pnpm dev

Teraz możesz otworzyć i przeglądać stronę internetową z poziomu przeglądarki, odwiedzając http://localhost:5173.

Budowanie strony internetowej

Spowoduje to skompilowanie wszystkich plików markdown do statycznych plików html i umieszczenie ich w .vitepress/dist:

pnpm build

Podgląd zbudowanej witryny

Spowoduje to uruchomienie lokalnego serwera na porcie 4173, który będzie obsługiwał zawartość znalezioną w .vitepress/dist:

pnpm preview

Otwieranie żądania ściągnięcia

Gdy już będziesz zadowolony ze zmian, możesz je „wcisnąć”:

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

Następnie kliknij link w wynikach polecenia git push, aby otworzyć żądanie ściągnięcia.

2. stage:expansion Wskazówki dotyczące rozbudowy w razie potrzeby

Jeśli zespół dokumentacyjny uważa, że możesz rozszerzyć swoje żądanie ściągnięcia, członek zespołu doda do niego etykietę stage:expansion wraz z komentarzem wyjaśniającym, co ich zdaniem możesz rozszerzyć. Jeśli zgadzasz się z tą sugestią, możesz rozszerzyć swoje żądanie ściągnięcia.

Jeśli nie chcesz rozszerzać swojego pull requestu, ale nie masz nic przeciwko temu, żeby ktoś inny rozszerzył go później, powinieneś utworzyć zgłoszenie na stronie zgłoszeń i wyjaśnić, co Twoim zdaniem można rozszerzyć. Zespół zajmujący się dokumentacją doda następnie do Twojego PR etykietę help-wanted.

3. stage:verification Weryfikacja treści

To najważniejszy etap, gdyż gwarantuje, że treść jest poprawna i zgodna ze stylem dokumentacji Fabric.

Na tym etapie należy odpowiedzieć na następujące pytania:

• Czy cała treść jest poprawna?
• Czy wszystkie treści są aktualne?
• Czy treść obejmuje wszystkie przypadki, np. różne systemy operacyjne?

4. stage:cleanup Czyszczenie

Na tym etapie dzieje się, co następuje:

• Naprawa wszelkich błędów gramatycznych za pomocą languagetool
• Linting wszystkich plików markdown przy użyciu markdownlint
• Formatowanie całego kodu Java przy użyciu Checkstyle
• Inne różne poprawki lub ulepszenia

framework Struktura wkładu

Framework odnosi się do wewnętrznej struktury witryny internetowej. Wszelkie żądania ściągnięcia, które modyfikują framework witryny internetowej, będą oznaczone etykietą framework.

Żądania ściągnięcia frameworka należy składać wyłącznie po konsultacji z zespołem dokumentacji na Discord Fabric lub za pośrednictwem zgłoszenia.

INFO

Modyfikowanie plików paska bocznego i konfiguracji paska nawigacyjnego nie jest liczone jako żądanie ściągnięcia struktury.

Wytyczne dotyczące stylu

Jeśli masz jakiekolwiek wątpliwości, możesz zapytać na Fabric Discord lub za pośrednictwem dyskusji GitHub.

Napisz oryginał w amerykańskim angielskim

Wszystkie oryginalne dokumenty są sporządzone w języku angielskim, zgodnie z amerykańskimi zasadami gramatyki.

Dodaj dane do frontmatter

Każda strona musi mieć tytuł i opis w tekście początkowym.

Pamiętaj, aby dodać także swoją nazwę użytkownika GitHub do „authors” w części frontmatter pliku Markdown! W ten sposób będziemy mogli przyznać Ci należne uznanie.

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

Dodaj kotwice do nagłówków

Każdy nagłówek musi mieć kotwicę, która służy do linkowania do tego nagłówka:

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

Kotwica musi zawierać małe litery, cyfry i myślniki.

Umieść kod w przykładowym modzie

Jeśli tworzysz lub modyfikujesz strony zawierające kod, umieść go w odpowiednim miejscu w przykładowym modzie (znajdującym się w folderze /reference w repozytorium). Następnie użyj funkcji fragmentu kodu oferowanej przez vitepress, aby osadzić kod.

Na przykład, aby podświetlić linie 15-21 pliku examplemod.java z moda:

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;

//#entrypoint
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);

	//#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, Identifier.fromNamespaceAndPath(ExampleMod.MOD_ID, "sparkle_particle"), SPARKLE_PARTICLE);
		//#particle_register_main
		// :::datagen-world:biome-modifications
		// Spawns everywhere in the overworld
		BiomeModifications.addFeature(
				BiomeSelectors.foundInOverworld(),
				GenerationStep.Decoration.UNDERGROUND_ORES,
				ExampleModWorldPlacedFeatures.DIAMOND_BLOCK_ORE_PLACED_KEY
		);
		// :::datagen-world:biome-modifications

		// :::datagen-world:selective-biome-modifications
		// Spawns in forest biomes only
		BiomeModifications.addFeature(
				BiomeSelectors.tag(BiomeTags.IS_FOREST),
				GenerationStep.Decoration.VEGETAL_DECORATION,
				ExampleModWorldPlacedFeatures.DIAMOND_TREE_PLACED_KEY
		);
		// :::datagen-world:selective-biome-modifications

		// #tooltip_provider
		ItemComponentTooltipProviderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		// #tooltip_provider
		// #advanced_tooltip_provider
		ItemComponentTooltipProviderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.ADVANCED_CUSTOM_COMPONENT);
		// #advanced_tooltip_provider
		//#entrypoint
	}
}

Jeśli potrzebujesz większego zakresu kontroli, możesz skorzystać z funkcji transkluzji z markdown-it-vuepress-code-snippet-enhanced.

Na przykład spowoduje to osadzenie sekcji pliku powyżej oznaczonych tagiem #entrypoint:

md

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

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

Utwórz pasek boczny dla każdej nowej sekcji

Jeśli tworzysz nową sekcję, powinieneś utworzyć nowy pasek boczny w folderze .vitepress/sidebars i dodać go do pliku i18n.mts.

Jeśli potrzebujesz pomocy, zapytaj na kanale #docs Fabric Discord.

Dodaj nowe strony do odpowiednich pasków bocznych

Podczas tworzenia nowej strony należy dodać ją do odpowiedniego paska bocznego w folderze .vitepress/sidebars.

Jeśli potrzebujesz pomocy, zapytaj na Discordzie Fabric w kanale #docs.

Umieść media w /assets

Wszystkie obrazy należy umieścić w odpowiednim miejscu w folderze /public/assets.

Używaj linków względnych!

Wynika to z obowiązującego systemu kontroli wersji, który przetwarza łącza w celu wcześniejszego dodania wersji. Jeśli użyjesz linków bezwzględnych, numer wersji nie zostanie dodany do linku.

Nie należy także dodawać do linku rozszerzenia pliku.

Na przykład, aby utworzyć link do strony znajdującej się w /players/index.md ze strony /develop/index.md, należy wykonać następujące czynności:

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