此网站使用 VitePress 从多个 Markdown 文件生成静态 HTML 网页。 您应该熟悉 VitePress 所支持的 Markdown 扩展语法，参见此链接。

贡献此网站有三种方法：

• 翻译文档
• 贡献内容
• 贡献网页框架

所有贡献应该遵守我们的样式指南。

翻译文档

如果想将文档翻译为你的语言，可以在 Fabric Crowdin 页面翻译。

new-content 贡献内容

贡献内容是贡献 Fabric 文档的主要方式。

所有内容贡献都经过以下步骤，每个步骤都与一个标签相关联：

1. 本地 准备您的更改并推出一个PR
2. stage:expansion：扩展指南（如果可能）
3. stage:verification：内容验证
4. 步骤：整理中：语法检查中...
5. 步骤：准备：准备合并！

所有的内容都应当遵循我们的样式指南。

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:3000 预览您的更改，并自动在修改时重载页面。

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 标签到您的拉去请求，并附上一条评论解释为什么他认为可以拓展。 如果同意建议，可以扩展你的拉取请求。

如果不想扩展您的拉取请求，但乐于让其他人在未来扩展它，最好在议题页面创建议题，并解释您想如何扩展。 之后文档制作团队将会在你的PR中加入帮助-追踪标签

3. stage:verification 内容验证

这是最重要的阶段，因为这能确保内容准确且遵循 Fabric 文档的样式指南。

在这一步，以下问题应被回答：

• 所有内容都正确吗？
• 所有内容都是最新的吗？
• 内容是否涵盖所有情况，例如不同的操作系统？

4. stage:cleanup 清理

在这一步，会发生以下内容：

• 使用LanguageTool来修复一切语法问题
• 使用 markdownlint 检查所有 Markdown 文件
• 使用检查工具来格式化所有Java代码
• 其它杂项翻译或优化

framework 贡献网页框架

“框架”指的是网站的内部结构，任何修改网站框架的拉取请求都应该用 framework 标签标记。

您应该在咨询了 Fabric Discord 上的文档团队或通过一个 issue 后再发起框架相关的拉取请求。

INFO

修改侧边栏文件和导航栏配置不算作框架拉取请求。

样式指南

如果有任何疑问，请在 Fabric Discord 或 GitHub Discussions 中提出。

用美式英语写原文

所有原始文档都使用英文书写，遵循美国的语法规则。

给 Frontmatter 添加数据

所有页面必须在 frontmatter 中有 title 和 description。

记得还要在 Markdown 文件的 frontmatter 中的 authors 添加你的 GitHub 用户名！ 这种方式可以给你适当的致谢。

---
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 提供的代码片段功能来嵌入代码。

例如，高亮参考模组中的 FabricDocsReference.java 的第 15-21 行：

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

如果需要更大范围的控制，可以使用来自 markdown-it-vuepress-code-snippet-enhanced 的 transclude 功能。

例如，这会嵌入上面的文件中被标记 #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 文件。

如果这个需要帮助，请在 Fabric Discord 的 #docs 频道提问。

将新页面添加到相关的侧边栏

写新页面时，应该将其添加到 .vitepress/sidebars 文件夹中的相关侧边栏。

还是那句，如果需要帮助，请在 Fabric Discord 的 #docs 频道提问。

把媒体放在 /assets 中

任何图片都应该放在 /assets 文件夹中的适当位置。

使用相对链接！ 使用相对链接！

这是因为现有的版本控制系统会预处理链接，以便事先添加版本号。 如果您使用绝对链接，版本号将不会添加到链接中。

你也不能够给链接添加扩展名。

例如，要从页面 /players/index.md 链接到位于 /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)