Wytyczne współtworzenia

Ta strona używa VitePress do generowania statycznego HTML-a z różnych plików Markdown. Warto zapoznać się z rozszerzeniami Markdown, które obsługuje VitePress, tutaj.

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

Tworzenie nowych treści jest głównym sposobem na przyczynienie się do rozwoju dokumentacji Fabric.

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

1. lokalnie Przygotuj swoje zmiany i utwórz PR
2. stage:expansion: Pomoc w rozbudowie treści (w razie potrzeby)
3. stage:verification: Weryfikowanie treści
4. stage:cleanup: Sprawdzanie gramatyki, błędów itp.
5. stage:ready: Gotowe do wdrożenia!

Wszystkie treści muszą być zgodne z naszymi wytycznymi dotyczącymi stylu.

1. Przygotuj swoje zmiany

Ta strona jest open-source i rozwijana jest w repozytorium na GitHubie, co oznacza, że polegamy na GitHubowym schemacie pracy:

1. Sforkuj repozytorium GitHub
2. Stwórz nową gałąź w swoim forku
3. Wprowadź zmiany na tej gałęzi
4. Utwórz Pull Request w oryginalnym repozytorium

Więcej informacji o GitHubowym schemacie pracy znajdziesz tutaj.

Zmiany możesz wprowadzać bezpośrednio z interfejsu internetowego na GitHubie lub lokalnie edytować i podglądać zmiany na stronie.

Klonowanie swojego forka

Jeśli chcesz wprowadzać zmiany lokalnie, będzie ci potrzebny Git.

Po jego zainstalowaniu sklonuj swoje sforkowane 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 lokalnie podglądać swoje zmiany na stronie, będzie ci potrzebny Node.js 18+.

Po jego zainstalowaniu zainstaluj wszystkie wymagane zależności za pomocą:

npm install

Uruchamianie serwera deweloperskiego

Serwer ten pozwala na podglądanie w czasie rzeczywistym wprowadzonych zmian lokalnie pod adresem localhost:5173, automatycznie przeładowując stronę po wprowadzeniu zmian. Uruchamia się go za pomocą:

npm run dev

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

Budowanie strony

Spowoduje to skompilowanie wszystkich plików Markdown do statycznych plików HTML i umieszczenie ich w .vitepress/dist.

npm run build

Podglądanie zbudowanej strony

Spowoduje to uruchomienie lokalnego serwera na porcie 4173 wyświetlającego zawartość znajdującą się w .vitepress/dist.

npm run preview

Tworzenie Pull Requesta

Po wprowadzeniu odpowiednich zmian możesz je spushować za pomocą:

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

Następnie, aby utworzyć PR, otwórz link wyświetlony w wyniku polecenia git push.

2. stage:expansion Pomoc w rozbudowie treści

Jeśli nasz zespół od dokumentacji uzna, że twój PR można rozbudować, członek zespołu doda do niego etykietę stage:expansion wraz z komentarzem wyjaśniającym, co mogłoby zostać rozbudowane. Jeśli się zgadasz z podanymi sugestiami, możesz rozbudować swój PR.

Jeśli nie chcesz rozbudowywać swojego PR, ale chcesz, aby zrobił to ktoś inny w późniejszym terminie, musisz utworzyć zgłoszenie w zakładce „Issues” i wyjaśnić, co mogłoby zostać rozbudowane. Nasz zespół od dokumentacji doda następnie do twojego PR etykietę help-wanted.

3. stage:verification Weryfikowanie treści

Jest to najważniejszy etap, ponieważ zapewnia, że treść jest poprawna i zgodna z wytycznymi dokumentacji Fabric dotyczącymi stylu.

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

• Czy wszystkie treści są poprawne?
• Czy wszystkie treści są aktualne?
• Czy treść obejmuje wszystkie przypadki, takie jak różne systemy operacyjne?

4. stage:cleanup Porządkowanie

Na tym etapie wykonuje się następujące czynności:

• Poprawianie wszelkich błędów gramatycznych za pomocą LanguageTool
• Analizowanie (linting) pod kątem potencjalnych błędów wszystkich plików Markdown za pomocą markdownlint
• Formatowanie całego kodu Java za pomocą Checkstyle
• Inne drobne poprawki lub ulepszenia

framework Współtworzenie frameworka

Framework odnosi się do wewnętrznej struktury strony. Wszelkie pull requesty, które go modyfikują będą oznaczone etykietą framework.

Pull requesty dotyczące frameworka należy tworzyć wyłącznie po konsultacji z zespołem od dokumentacji na Discordzie Fabric lub za pośrednictwem zgłoszenia.

INFO

Modyfikowanie plików paska bocznego i konfiguracji paska nawigacyjnego nie jest zaliczane jako pull request dotyczący frameworka.

Wytyczne dotyczące stylu

Jeśli nie masz pewności co do czegokolwiek, możesz zapytać na Discordzie Fabric lub za pośrednictwem dyskusji na GitHubie.

Pisz wszystko w amerykańskim angielskim

Cała oryginalna dokumentacja jest napisana w języku angielskim, zgodnie z amerykańskimi zasadami gramatyki.

Dodaj metadane do strony

Każda strona musi zawierać tytuł (title) oraz opis (description) w segmencie nazywanym Frontmatter, który znajduje się na początku pliku.

Pamiętaj również dodać swoją nazwę użytkownika na GitHubie w polu authors! W ten sposób będziemy mogli przyznać Ci należne wyróżnienie.

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

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

...

Dodaj zakotwiczenia do nagłówków

Każdy nagłówek być zakotwiczony, aby można było go zlinkować:

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

Zakotwiczenie może składać się tylko z małych liter, myślników i cyfr.

Umieść kod w modzie /reference

Jeśli tworzysz lub modyfikujesz strony zawierające kod, umieść kod w odpowiednim miejscu w modzie referencyjnym (znajdującym się w folderze /reference repozytorium). Następnie użyj funkcji importowania fragmentów kodu oferowanej przez VitePress, aby osadzić kod.

Na przykład, aby wyróżnić linie 15-21 pliku FabricDocsReference.java z moda referencyjnego, użyj:

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
	}
}

Jeśli potrzebujesz większej kontroli, możesz użyć funkcji transkluzji z markdown-it-vuepress-code-snippet-enhanced.

Dla przykładu ten kod osadzi sekcje powyższego pliku, które są oznaczone tagiem #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!");
	}
}

Utwórz pasek boczny dla każdej nowej sekcji

Jeśli tworzysz nową sekcję musisz stworzyć dla niej nowy pasek boczny w folderze .vitepress/sidebars i dodać go do pliku i18n.mts.

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

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 z tym pomocy, zapytaj na Discordzie Fabric na kanale #docs.

Umieść multimedia w folderze /assets

Wszelkie obrazy powinny zostać umieszczone w odpowiednim miejscu w folderze /public/assets.

Używaj linków względnych!

Powodem tego jest istniejący system wersjonowania, który przetwarza linki, dodając na początku numer wersji. Jeśli użyjesz linku bezwzględnego, numer wersji nie zostanie do niego dodany.

Nie należy również dodawać rozszerzenia pliku do linku.

Na przykład, aby utworzyć link do strony znajdującej się w /players/index.md ze strony /develop/index.md, należy zrobić to w następujący sposób:

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