Інструкції щодо внеску 26.1.2

Інструкції щодо додавання до документації Fabric.

Цей сайт використовує VitePress для створення статичного HTML з різних файлів Markdown. Ви повинні ознайомитися з розширеннями Markdown, які підтримує VitePress.

Ви можете зробити свій внесок у розвиток цього сайту трьома способами:

• Переклад документації
• Доповнення вмісту
• Доповнення фреймворку

Усі внески мають відповідати нашим правилам стилю.

Переклад документації

Якщо ви хочете перекласти документацію вашою мовою, ви можете зробити це на сторінці Fabric Crowdin.

new-content Доповнення вмісту

Внесок умісту є основним способом внеску в документацію Fabric.

Усі внески вмісту проходять наступні етапи, кожен із яких пов’язаний із міткою:

1. locally — підготуйте свої зміни та створіть запит на зміни
2. stage:expansion — вказівки щодо розширення, якщо це необхідно
3. stage:verification — перевірка вмісту
4. stage:cleanup — граматика, лінтування…
5. stage:ready: — готово до об’єднання!

Весь вміст має відповідати нашим правилам стилю.

1. Підготуйте свої зміни

Ця сторінка має відкритий код у репозиторії GitHub, що означає, що ми покладаємося на потік GitHub:

1. Форк репозиторію GitHub
2. Створіть нову гілку у вашому форку
3. Унесіть зміни в цю гілку
4. Відкрийте запит на зміни в початковому репозиторії

Ви можете прочитати більше про потік GitHub.

Ви можете вносити зміни за допомогою вебінтерфейсу на GitHub або розробляти та переглядати сторінку локально.

Клонування вашого форку

Якщо ви хочете розробляти локально, вам потрібно буде встановити Git.

Після цього клонуйте свій форк репозиторію за допомогою:

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

Установлення залежностей

Якщо ви хочете переглянути свої зміни локально, вам потрібно буде встановити Node.js 18+ та pnpm.

Після цього переконайтеся, що встановили всі залежності за допомогою:

pnpm install

Запуск сервера розробки

Це дозволить вам переглянути ваші зміни локально на localhost:5173 і автоматично перезавантажить сторінку, коли ви внесете зміни.

pnpm dev

Тепер ви можете відкривати та переглядати сторінку у браузері, відвідавши http://localhost:5173.

Створення сторінки

Це скомпілює всі файли Markdown у статичні файли HTML і розмістить їх у .vitepress/dist:

pnpm build

Попередній перегляд створеної сторінки

Це запустить локальний сервер на порту 4173, який буде обслуговувати вміст, знайдений у теці .vitepress/dist:

pnpm preview

Відкриття запиту на зміни

Після того, як ви задоволені своїми змінами, ви можете push свої зміни:

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

Потім перейдіть за посиланням у виводі git push, щоб відкрити запит на зміни.

2. stage:expansion — рекомендації щодо розширення, якщо це необхідно

Якщо команда документації вважає, що ви можете розширити свій запит на зміну, член команди додасть мітку stage:expansion до вашого запиту разом із коментарем, у якому пояснюється, що, на їхню думку, ви можете розширити. Якщо ви згодні з пропозицією, ви можете розширити свій запит на зміну.

Якщо ви не хочете розширювати свій запит на зміни, але ви раді, щоб хтось інший розширив його пізніше, вам слід створити проблему на [сторінці проблем](https://github.com/FabricMC/ fabric-docs/issues) і поясніть, що, на вашу думку, можна розширити. Потім команда документації додасть мітку help-wanted до вашого запиту.

3. stage:verification — перевірка вмісту

Це найважливіший етап, оскільки він гарантує, що вміст є точним і відповідає посібнику зі стилю документації Fabric.

На цьому етапі необхідно відповісти на наступні питання:

• Увесь уміст правильний?
• Увесь уміст актуальний?
• Чи охоплює вміст усі випадки, наприклад різні операційні системи?

4. stage:cleanup — очищення

На цьому етапі відбувається наступне:

• Виправлення будь-яких граматичних проблем за допомогою LanguageTool
• Лінтування всіх файлів Markdown за допомогою markdownlint
• Форматування усього коду Java за допомогою Checkstyle
• Інші різноманітні виправлення та покращення

framework — Доповнення фреймворку

Фреймворк належить до внутрішньої структури сайту, будь-які запити на зміни, які змінюють фреймворк сайту, позначатимуться міткою framework.

Ви дійсно повинні робити запити на зміну фреймворку лише після консультації з командою документації на Fabric Discord або через проблему.

INFO

Зміна файлів бокової панелі та налаштувань навігаційної панелі не вважається запитом на зміну фреймворку.

Посібник зі стилю

Якщо ви в чомусь не впевнені, ви можете запитати в Fabric Discord або через дискусії GitHub.

Пишіть оригінал американською англійською мовою

Уся оригінальна документація написана англійською мовою з дотриманням американських правил граматики.

Додайте дані до передньої частини

Кожна сторінка повинна мати description і title на передній частині.

Не забувайте також додати своє ім’я користувача GitHub до authors у передній частині файлу Markdown! Таким чином ми можемо надати вам належну згадку.

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

Додайте прив’язки до заголовків

Кожен заголовок повинен мати прив’язку, яка використовується для посилання на цей заголовок:

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

Прив'язка повинна використовувати лише малі літери, цифри та дефіс.

Розмістіть код у прикладі мода

Якщо ви створюєте або змінюєте сторінки, що містять код, розмістіть код у відповідному місці в прикладі мода (розташованого в теці /reference сховища). Потім скористайтеся функцією фрагмента коду, запропонованою VitePress, щоб вставити код.

Наприклад, щоб виділити рядки 15-21 файлу ExampleMod.java з мода:

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

Якщо вам потрібен більший діапазон контролю, ви можете скористатися функцією перенесення з markdown-it-vuepress-code-snippet-enhanced.

Наприклад, це дозволить вставити розділи файлу вище, позначені теґом #entrypoint:

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

Створіть бокову панель для кожного нового розділу

Якщо ви створюєте новий розділ, вам слід створити нову бокову панель у теці .vitepress/sidebars й додати її до файлу i18n.mts.

Якщо вам потрібна допомога з цим, запитайте на каналі #docs Fabric Discord.

Додайте нові сторінки до відповідних бокових панелей

Створюючи нову сторінку, ви повинні додати її до відповідної бокової панелі в теці .vitepress/sidebars.

Знову ж таки, якщо вам потрібна допомога, запитайте у Fabric Discord на каналі #docs.

Розмістіть медіа в /assets

Будь-які зображення слід розміщувати у відповідному місці в теці /public/assets.

Використовуйте відносні посилання!

Це пов’язано з наявною системою керування версіями, яка попередньо оброблятиме посилання для додавання версії. Якщо ви використовуєте абсолютні посилання, номер версії не буде додано до посилання.

Ви також не повинні додавати розширення файлу до посилання.

Наприклад, щоб зробити посилання на сторінку, знайдену в /players/index.md зі сторінки /develop/index.md, вам потрібно буде зробити наступне:

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