✍️ ガイドの編集に参加する
説明が分かりにくいところや、紹介したい使い方があれば、ぜひ教えてください!
パソコンに開発用のソフトを入れなくても、ブラウザーから文章を直せます
編集したら、すぐ公開される?
「編集したら、すぐ公開される?」へのリンク編集しただけでは公開されません
変更案を送ったあと、運営が内容を確認してから正式なガイドへ反映します
| 操作 | 一般の編集者 |
|---|---|
| ガイドやソースを読む | できます |
| 自分のコピーで文章を直す | できます |
| 修正案をPRで送る | できます |
| PRにコメントする | できます |
| PRを正式なガイドへ反映する | できません |
| 公開設定や権限を変える | できません |
正式なガイドへの反映は、公開担当の humisan が行います 公開設定や権限の変更は、管理者の操作です
一般の編集者にマージ権限を渡す必要はありません
mainにはPRと自動チェックを必須にし、反映できる人をhumisanに限定しています
GitHubの言葉を知っておく
「GitHubの言葉を知っておく」へのリンク| 言葉 | このガイドでの意味 |
|---|---|
| リポジトリ | ガイドの文章やファイルをまとめて置く場所 |
| Fork(フォーク) | 自分のアカウントに作る、編集用のコピー |
| ブランチ | 変更ごとに分ける作業場所 |
| Commit(コミット) | 修正内容を保存して、変更の記録を残すこと |
| PR(プルリクエスト) | 「この変更を採用してください」と運営へ送る提案 |
| Review(レビュー) | 提案された内容を確認すること |
| Merge(マージ) | 提案を正式なガイドへ取り込むこと |
main |
現在公開しているガイドの元になるブランチ |
すべて覚えてから始めなくても大丈夫です!
迷ったら、この表と手順を見ながら進めてください
すでにある記事を直す
「すでにある記事を直す」へのリンク1. 編集する記事を開く
「1. 編集する記事を開く」へのリンク直したい記事の下にある 「ページを編集」 を押します
GitHubで、その記事のファイルが開きます
GitHubのアカウントがない場合は、アカウントを作成してログインしてください
ガイドへの参加に有料プランは必要ありません
2. 自分の編集用コピーを作る
「2. 自分の編集用コピーを作る」へのリンク初めて編集するときは、Forkの作成が案内される場合があります
Fork this repositoryなどのボタンから、自分のアカウントにコピーを作ります
すでにForkがある場合は、そのコピーを使えます
編集画面が開かないときは、元のリポジトリの Fork を押して作成し、自分のコピーから該当するファイルを開いてください
3. 文章を編集する
「3. 文章を編集する」へのリンク鉛筆のボタン(Edit this file)から編集します
先頭の---で囲まれた部分は、記事名や説明の設定です
文章だけを直す場合は、設定部分を残して本文を編集してください
Previewで、見出し・箇条書き・コマンドの表示を確認できます
4. 変更を保存する
「4. 変更を保存する」へのリンクCommit changes…を押し、変更内容を短く日本語で書きます
スポーンへの移動手順を分かりやすくする新しいブランチを作る選択肢がある場合は、変更用のブランチを作ります
名前はdocs/update-spawn-guideのように、docs/から始めてください
この保存は自分のコピーの変更です
正式なガイドは、まだ書き換わりません
5. PRを送る
「5. PRを送る」へのリンクPropose changesや Compare & pull requestからPRの画面へ進みます
表示がない場合は、自分のForkの Pull requests → New pull requestから作成できます
送り先を確認してください
| 項目 | 選ぶ内容 |
|---|---|
| base repository(送り先) | hnmt-mc/hnmt-docs |
| base(反映先) | main |
| head repository(変更元) | 自分のFork |
| compare(変更したブランチ) | 今回作業したブランチ |
タイトルに「何を直したか」、説明に「なぜ直したか」「どう確認したか」を書きます
Files changedで、自分が変更したファイルだけが含まれているか確認してください
Create pull requestを押すと、運営へ変更案を送れます!
新しい記事を追加する
「新しい記事を追加する」へのリンク1. 記事を置く場所を選ぶ
「1. 記事を置く場所を選ぶ」へのリンク自分のForkで、内容に合うフォルダーを開きます
| フォルダー | 掲載する内容 |
|---|---|
src/content/docs/start/ |
初参加の案内、最初にすること |
src/content/docs/life/ |
ホーム、移動、会話などの便利機能 |
src/content/docs/town/ |
TownyChat、お店ガイドの入口 |
src/content/docs/quickshop/ |
QuickShop-Hikariの取引・作成・管理 |
src/content/docs/towny/ |
Townyの住民・土地・町・国家の使い方とコマンド |
2. ファイルを作る
「2. ファイルを作る」へのリンクAdd file → Create new fileを選びます
ファイル名は、英小文字とハイフンを使った.md形式にします
たとえば、Townyの土地を確認する記事なら、towny/check-land.mdのような名前です
towny/フォルダーを開いた状態なら、入力する名前はcheck-land.mdだけで大丈夫です
3. 記事名・説明・本文を書く
「3. 記事名・説明・本文を書く」へのリンク先頭にはtitleとdescriptionが必要です
次は、既存のホーム案内を短く書いた記入例です
---title: 🏠 ホームを使うdescription: 今いる場所をホームに登録する手順---
よく訪れる場所を登録すると、あとから戻りやすくなります!
## 登録する
1. 安全な足場の上に立ちます2. `/home`で管理画面を開きます3. 解放済みのエンダーアイをクリックします
ボーダーの外など、安全でない場所には登録できません新しい記事では、掲載したい機能の内容に書き換えてください
画面で選ぶ項目、入力するコマンド、操作後の結果まで書くと、初めての人にも伝わります
保存したあと、既存記事の修正と同じ手順でPRを送ります
記事が採用されると、置いたフォルダーに合わせてメニューにも表示されます
新しいセクションを作る
「新しいセクションを作る」へのリンク「セクション」には、サイドバーの大分類・分類の中の小分類・記事内の見出しがあります 作りたいものに合わせて、変更する場所を選んでください
| 作りたいもの | 変更する場所 |
|---|---|
| 「町とお店」のようなサイドバーの大分類 | 新しいフォルダーとastro.config.mjs |
| 「暮らしの便利機能」の中に置く小分類 | 既存フォルダー内の新しいフォルダー |
| ひとつの記事の中の見出し | 記事のMarkdown |
サイドバーに新しい大分類を追加する
「サイドバーに新しい大分類を追加する」へのリンク例として、「移動の案内」という大分類を作る手順を紹介します 既存のフォルダーを移動する必要はありません
1. 新しいフォルダーに最初の記事を作ります
自分のForkで Add file → Create new fileを選び、次の名前を入力します
src/content/docs/travel/spawn.mdGitHubでは、ファイル名にフォルダーの名前を含めると、一緒にフォルダーも作られます リポジトリの一番上から作る場合の入力例です
最初の記事には、記事名・説明・本文を書いてください
次は/spawnの案内を使った記入例です
---title: 🧭 スポーンへの移動description: 共通スポーンに戻る手順sidebar: order: 1---
`/spawn`で共通スポーンに戻れます
## 移動する
1. 安全な場所で`/spawn`を実行します2. カウントダウンが終わるまで、その場で待ちます
待機中に動いたりダメージを受けたりすると、移動が取り消されますこの例をそのまま追加すると、既存のスポーン案内と内容が重なります 実際のPRでは、追加したい分類に合う記事に書き換えてください
2. 同じブランチでメニューの設定を編集します
リポジトリの一番上にあるastro.config.mjsを開きます
sidebar: [で始まる一覧の中へ、次の項目を追加してください
{ label: '移動の案内', items: [{ autogenerate: { directory: 'travel' } }] },label:メニューに表示する名前です 日本語で書けますdirectory:記事を置いたフォルダー名ですsrc/content/docs/より下の名前を書きます- 一覧の中の位置:メニューに並ぶ順番になります
フォルダーを作るだけでは、新しい大分類はメニューに追加されません 最初の記事とメニュー設定を、同じブランチ・同じPRに含めてください
3. 表示とPRの内容を確認します
- フォルダー名と
directoryの名前が一致しているか - 最初の記事が入っているか
labelが分かりやすい名前になっているか- 追加した項目の末尾のカンマや、かっこを消していないか
- PRのFiles changedに、記事と
astro.config.mjsの両方が入っているか
あとは、通常の編集と同じ手順でPRを送ります 追加した理由も書いて、運営の確認を待ってください
既存カテゴリの中に小分類を作る
「既存カテゴリの中に小分類を作る」へのリンクたとえば「暮らしの便利機能」の中に「移動」をまとめたい場合は、life/の中にフォルダーを作ります
src/content/docs/life/travel/spawn.md既存のlifeは自動表示する設定になっているので、その中の小分類と記事はサイドバーに反映されます
この場合は、astro.config.mjsへの大分類の追加は不要です
フォルダー名だけで自動生成する小分類は、通常そのフォルダー名が表示名になります 日本語の名前にしたい場合は、PRに希望する名前を書いてください 運営がサイドバーの設定で調整します
記事内に見出しを作る
「記事内に見出しを作る」へのリンク記事の中を区切るだけなら、Markdownに##や###を追加します
## ホームに移動する
登録済みのホームを左クリックすると、移動が始まります
### 移動が取り消されたとき
安全な場所で立ち止まり、もう一度実行してください##は大きな見出し、###はその中の小さな見出しです
記事の目次に表示されますが、サイドバーの新しい大分類にはなりません
PRを送ったあとは
「PRを送ったあとは」へのリンク- 自動チェックが、リンクやファイルの形式を確認します
- 運営が、文章と実際の操作内容を確認します
- 修正のお願いがあれば、同じブランチで直して保存します
- 運営がマージすると、自動公開が始まります
- 公開が成功すると、サイトの記事が更新されます
自動チェックが緑になっても、まだ採用・公開されたわけではありません
一般の編集者は、マージ操作を行わずに運営の確認を待ってください
修正するときに新しいPRを作り直す必要はありません
同じブランチに保存すると、開いているPRへ追加の変更が反映されます
困ったときは
「困ったときは」へのリンク| 状況 | 対応 |
|---|---|
| 編集ボタンが見つからない | GitHubにログインし、自分のForkのファイルを開きます |
| 「変更がない」と表示される | 保存できているか、変更元のブランチを正しく選んでいるか確認します |
| 自動チェックが赤い | PRのChecksから内容を確認します 分からなければ、そのPRにコメントしてください |
| マージボタンを押せない | 一般の編集者では正常です 運営が反映します |
| ファイルが競合している | 無理に上書きせず、PRにコメントして運営へ相談してください |
| マージ後も記事が変わらない | 公開処理と表示への反映に少し時間がかかる場合があります 少し待って再読み込みしてください |
文章を直すのが難しければ、Issuesから「どの記事の、どこが分かりにくいか」を伝えるだけでも大丈夫です!
書くときに大切にしたいこと
「書くときに大切にしたいこと」へのリンク- 実際に使える手順を、初めての人にも分かる言葉で書く
- 権限や設定によって変わる操作は、その条件を書く
- 短い案内は軽い文面にし、説明が続くときは「。」で文を区切る。話題が変わったら段落を分ける
- 今使える手順を案内し、使えない古いコマンドとの比較は載せない
- 個人情報、非公開の設定や管理画面、秘密情報を載せない
- 外部の画像や文章を使う場合は、掲載してよいものか確認する
- GitHubには公開してよい表示名を使い、メールアドレスの非公開設定も確認する
開発環境での確認やブランチの詳しいルールは、CONTRIBUTING.mdにまとめています
