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

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

WARNING

Ця сторінка написана для версії 1.21.4. Документація для старіших версій може бути неповною.

Цей сайт використовує 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+.

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

npm install

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

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

npm run dev

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

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

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

npm run build

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

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

npm run preview

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

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

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

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

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

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

Якщо ви не хочете розширювати свій запит на зміни, але ви раді, щоб хтось інший розширив його пізніше, вам слід створити проблему на сторінці проблем і поясніть, що, на вашу думку, можна розширити. Потім команда документації додасть мітку help-wanted до вашого запиту.

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

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

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

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

4. stage:cleanup Очищення

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

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

framework Додатковий каркас

Каркас стосується внутрішньої структури сторінки, будь-які запити на зміни, які змінюють каркас сторінки, позначатимуться міткою framework.

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

INFO

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

Правила стилю

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

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

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

Додайте дані до Frontmatter

Кожна сторінка повинна мати 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

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

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

md

<<< @/reference/1.21.4/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.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.particle.v1.FabricParticleTypes;
import net.minecraft.core.Registry;
import net.minecraft.core.particles.SimpleParticleType;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.resources.ResourceLocation;

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

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

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

md

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

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

Якщо ви створюєте новий розділ, вам слід створити нову бічну панель у теці .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)