貢献ガイドライン

このWebサイトは、Markdownファイルから静的HTMLを生成するのに VitePress を使っています。 VitePress がサポートする Markdown 拡張機能については、こちらでよく理解しておく必要があります。

この Web サイトに貢献するには、次の 3 つの方法があります。

• ドキュメントの翻訳
• コンテンツの寄稿
• フレームワークの貢献

すべての貢献は、スタイルガイドラインに従ってください。

ドキュメントの翻訳

ドキュメントを自分の言語に翻訳したい場合は、Fabric Crowdin ページで行うことができます。

<0>new-content</0> コンテンツの寄稿

コンテンツの寄稿は、Fabric ドキュメントに貢献する主な方法です。

すべてのコンテンツ投稿は次の段階を経て行われ、各段階にはラベルが関連付けられます。

1. locally 変更を準備してPRをプッシュ
2. stage:expansion: 必要に応じて拡張するためのガイダンス
3. stage:verification: コンテンツの検証
4. stage:cleanup: 文法、添削...
5. <0>stage:ready</0>: マージの準備完了！

すべてのコンテンツは、スタイルガイドラインに従ってください。

1. 変更を準備

このWebサイトはオープンソースで、Githubのリポジトリで管理されているため、Githubでの手順に依存しています。

1. GitHubのリポジトリをForkする
2. あなたのForkで新しいブランチを作成する
3. そのブランチで変更を作る
4. 元のリポジトリにPull Requestを作る

Github フローについて詳しくはこちらをご覧ください。

GitHub のWebインターフェースから編集するか、ローカルでWebサイトを構築してプレビューすることもできます。

あなたのForkをクローンする

ローカルで開発する場合は、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 にアクセスして、ブラウザからWebサイトを開いて閲覧できるようになります。

ウェブサイトの構築

これによりすべての Markdown ファイルが静的 HTML ファイルにコンパイルされ、.vitepress/dist に配置されます。

npm run build

構築した Web サイトのプレビュー

これにより、.vitepress/dist にあるコンテンツを提供するポート 4173 でローカル サーバーが起動します。

npm run preview

Pull Requestを作る

変更内容に満足したら、変更内容を push できます。

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

次に、git push の出力にあるリンクに従って PR を開きます。

2. stage:expansion 必要に応じて拡張するためのガイダンス

ドキュメンテーションチームがPull Requestを拡張できると判断した場合、チームのメンバーがPull Requestに stage:expansion ラベルを追加し、拡張できると思われる内容を説明するコメントをします。 提案に同意する場合は、Pull Requestを拡張できます。

自分でPull Requestを拡張するつもりはないが、後日他のユーザーが拡張しても構わない場合は、Issueページ で新しいIssueを作成し、拡張が必要と思われる内容を説明してください。 ドキュメンテーションチームは、あなたのPull Requestに help-wanted ラベルを追加します。

3. stage:verification コンテンツの検証

コンテンツが正確で、Fabricドキュメントのスタイルガイドに従っていることを確認するため、このステージが最も重要です。

このステージでは、次の質問に答える必要があります。

• すべての内容が正確ですか？
• すべての内容が最新ですか？
• 内容はOSの違いなど、あらゆる場合をカバーしているか？

4. stage:cleanup クリーンアップ

このステージでは、次のことが行われます。

• LanguageToolを使って、文法の問題や誤字を修正します。
• markdownlintを使って、リンティングします。
• Checkstyleを使って、Javaのコードをフォーマットします。
• その他の修正や改善

framework コントリビュートの枠組み

フレームワークとは、Webサイトの構造のことを指します。フレームワークを変更するPull Requestには framework ラベルがつけられます。

フレームワークのPull Requestは、Fabric Discordまたはissueでドキュメントチームに相談した後にのみ行う必要があります。

INFO

サイドバーとナビゲーションバーの設定の変更は、フレームワークのPull Requestとしてみなされません。

スタイルガイドライン

分からないことがあれば、Fabric DiscordまたはGitHub Discussionsで聞いてください。

原文をアメリカ英語で書く

オリジナルドキュメントはすべて、アメリカの文法規則に従って英語で書かれています。

Frontmatterにデータを追加

それぞれのページはtitileとdescriptionをfrontmatterに含んでいる必要があります。

MarkdownファイルのfrontmatterのauthorsにあなたのGitHubのユーザー名も忘れずに追加してください！ そうすればあなたに適切なクレジットを付与することができます。

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

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

...

見出しにアンカーを追加する

それぞれの見出しには、その見出しへのリンクに使用されるアンカーが必要です。

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

アンカーには、英小文字, 数字, ハイフン(-) のみを使用してください。

コードを/referenceのModに配置する

コードを含むページを作成または変更する場合は、リファレンスMOD（リポジトリの /reference フォルダにあります）内の適切な場所にコードを配置してください。 そして、VitePressが提供するコードスニペット機能を使ってコードを埋め込みます。

たとえば、FabricDocsReference.javaファイルの15行目から21行目をリファレンスモッドからハイライトするには

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

より大きな制御範囲が必要な場合は、markdown-it-vuepress-code-snippet-enhancedのtransclude機能を使うことができます。

たとえば、これは上のファイルの #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!");
	}
}

新しいセクションごとにサイドバーを作る

新しいセクションを作成する場合は、.vitepress/sidebarsフォルダに新しいサイドバーを作成し、i18n.mtsファイルに追加してください。

サポートが必要な場合は、Fabric Discord の #docs チャンネルで聞いてください。

関連するサイドバーに新しいページを追加する

新しいページを作成する際は、.vitepress/sidebarsフォルダ内の関連するサイドバーに追加してください。

繰り返しになりますが、サポートが必要な場合はFabric Discordの #docs チャンネルで聞いてください。

画像を/assetsに配置する

画像は/public/assets内の適切な場所に配置してください。

相対リンクを使う！

これはバージョン管理が導入されているためで、リンクはあらかじめバージョンを追加するように処理されます。 絶対リンクを使う場合、バージョン番号はリンクに追加されません。

また、リンクにファイルの拡張子を追加しないでください。

たとえば、/develop/index.mdから/players/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)