Руководство по внесению вклада 1.21.8

Руководство по внесению вклада в документацию Fabric

WARNING

Эта страница написана для версии 1.21.8.
Документация для старых версий может быть неполной.

Этот сайт использует VitePress для генерации статического HTML-кода из различных Markdown-файлов. Вы можете ознакомиться с Markdown-расширениями для VitePress здесь.

Есть три пути для внесения своего вклада для сайта:

• Перевод документации
• Вклад в содержимое
• Руководство по внесению вклада

Все материалы должны соответствовать нашим рекомендациям по стилю.

Перевод документации

Если вы хотите перевести документацию на свой язык, вы можете сделать это на странице Fabric на Crowdin.

new-content Внесение контента

Основной способ внести вклад в документацию Fabric — это внесение контента.

Все материалы, добавляемые в контент, проходят следующие этапы, каждому из которых соответствует метка:

1. локально Подготовьте свои изменения и отправьте PR
2. stage:expansion: Руководство по расширению при необходимости
3. этап:проверка: проверка содержимого
4. stage:cleanup: Грамматика, Линтер...
5. stage:ready: Готово к релизу!

Всё содержимое должно соответствовать нашим рекомендациям по стилю.

1. Подготовьте свои изменения

Этот сайт с открытым исходным кодом, он разрабатывается в репозитории GitHub, что означает, что мы полагаемся на поток GitHub:

1. Создайте форк репозитория на GitHub
2. Создайте новую ветку в вашем форке
3. Сделайте свои изменения в этой ветке
4. Откройте запрос на изменение в оригинальном репозитории (Pull Request)

Вы можете прочитать больше о потоке 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, чтобы открыть PR.

2. stage:expansion Руководство по расширению, если необходимо

Если команда по документированию считает, что вы могли бы расширить свой запрос, один из членов команды добавит метку stage:expansion к вашему запросу на извлечение вместе с комментарием, объясняющим, что, по их мнению, вы могли бы расширить. Если вы согласны с этим предложением, вы можете дополнить свой реквест.

Если вы не хотите дополнять свой реквест, но будете рады, что кто-то другой дополнит его позже, лучше всего создать пост на странице проблем и объяснить, что, по вашему мнению, можно было бы дополнить. Затем группа по документированию добавит метку требуется помощь к вашему PR.

3. stage:verification Проверка содержимого

Это самый важный этап, поскольку он гарантирует точность контента и его соответствие руководству по стилю Fabric Documentation.

На этом этапе необходимо ответить на следующие вопросы:

• Все ли содержания верно?
• Весь ли контент актуален?
• Охватывает ли контент все случаи, например, различные операционные системы?

4. этап:очистка Очистка

На этом этапе происходит следующее:

• Исправление любых грамматических ошибок с помощью LanguageTool
• Анализ всех файлов Markdown с помощью markdownlint
• Форматирование всего кода Java с использованием Checkstyle
• Другие различные исправления и улучшения

framework Вносящий вклад в фреймворк

Фреймворк относится к внутренней структуре веб-сайта. Любые запросы, которые изменяют фреймворк веб-сайта, будут помечены меткой framework.

К вашему сведению, вы должны делать pull requests, касающиеся фреймворка, только после консультации с командой документации на Discord-сервере Fabric или через issue.

INFO

Изменение файлов боковой панели и конфигурации панели навигации не считается pull request, касающимся фреймворка.

Стандарты оформления

Если вы насчёт чего-то не уверены, можете задать свой вопрос в Discord-сервере Fabric или через GitHub Discussions.

Корректура (проверка грамматики и т. д.)

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

Добавляем данные в начало файла

Все страницы должны иметь заголовок и описание.

Не забывайте также добавлять ваше имя пользователя 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 репозитория). Фрагмент кода будет выглядеть следующим образом:

Это выведет все линии с 15 по 21 из файла FabricDocsReference.java из мода с примерами:

md

<<< @/reference/1.21.8/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.core.Registry;
import net.minecraft.core.component.DataComponents;
import net.minecraft.core.particles.SimpleParticleType;
import net.minecraft.core.registries.BuiltInRegistries;
import net.minecraft.resources.ResourceLocation;

import net.fabricmc.api.ModInitializer;
import net.fabricmc.fabric.api.item.v1.ComponentTooltipAppenderRegistry;
import net.fabricmc.fabric.api.particle.v1.FabricParticleTypes;

import com.example.docs.component.ModComponents;

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

		// #tooltip_provider
		ComponentTooltipAppenderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		// #tooltip_provider
	}
}

Затем используйте функцию вставки кода от VitePress, чтобы встроить код, или, если вам требуется более широкий контроль, вы можете использовать функцию transclude из markdown-it-vuepress-code-snippet-enhanced.

Например, это встроит секции файла выше, которые помечены тегом #entrypoint:

md

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

		// #tooltip_provider
		ComponentTooltipAppenderRegistry.addAfter(DataComponents.DAMAGE, ModComponents.COMPONENT_WITH_TOOLTIP);
		// #tooltip_provider
	}
}

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

Если вы создаете новую категорию, вам следует создать новую боковую панель в папке .vitepress/sidebars и добавить её в файл config.mts.

Если вам нужна помощь с этим, спросите в дискорде Fabric в канале #docs.

⚠️ Ссылки на другие страницы должны быть относительными. ⚠️

При создании новой страницы вы должны добавить ее на соответствующую боковую панель в папке .vitepress/sidebars.

Опять же, если вам нужна помощь, спросите в дискорде Fabric в канале #docs.

Используйте /assets для хранения медиаконтента

Любые изображения должны находиться в соответствующем месте в папке /assets.

Используйте относительные ссылки! ⚠️ Если ты ссылаешься на другие страницы, используй относительные ссылки. ⚠️

Это требуется для правильной работы системы с разными версиями, которая заранее обрабатывает ссылки для добавления версии. Если вы используете обычные ссылки, номер версии не будет добавлен к ссылке.

Вы также не должны добавлять расширение файла к ссылке.

Например, для страницы в папке /players, ссылка на страницу installing-fabric по пути /players/installing-fabric.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)