From dfae6783cbdf8a6a785449f4e4927fd4e97af371 Mon Sep 17 00:00:00 2001
From: Tomachi <8929706+book000@users.noreply.github.com>
Date: Fri, 5 Jul 2024 10:50:54 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=E3=83=89=E3=82=AD=E3=83=A5=E3=83=A1?=
 =?UTF-8?q?=E3=83=B3=E3=83=88=E3=81=AE=E8=BF=BD=E5=8A=A0=20(#166)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: requirements.txtがutf16だったのでutf8

* chore: venvのignore追加

* docs: とりあえずコマンドひととおり

* ci: indexファイルの検証追加

* docs: featuresのドキュメント追加

* docs: features/index 更新

* Apply suggestions from code review

* Update docs/for-users/commands/clear.md
---
 .github/workflows/mkdocs.yml               |  24 +++-
 .gitignore                                 |   1 +
 docs/for-users/commands/.index-template.md |   3 +
 docs/for-users/commands/alias.md           |  55 +++++++++
 docs/for-users/commands/clear.md           |  12 ++
 docs/for-users/commands/ignore.md          |  41 +++++++
 docs/for-users/commands/index.md           |  14 +++
 docs/for-users/commands/join.md            |  20 +++
 docs/for-users/commands/leave.md           |  16 +++
 docs/for-users/commands/parse.md           |  17 +++
 docs/for-users/commands/reset-title.md     |  19 +++
 docs/for-users/commands/save-title.md      |  28 +++++
 docs/for-users/commands/speak.md           |  11 ++
 docs/for-users/commands/title.md           |  25 ++++
 docs/for-users/commands/vcspeaker.md       |  37 ++++++
 docs/for-users/commands/voice.md           |  34 ++++++
 docs/for-users/features/.index-template.md |   3 +
 docs/for-users/features/alias.md           |   4 +
 docs/for-users/features/index.md           |   4 +
 docs/for-users/features/title.md           |   4 +
 docs/for-users/index.md                    |   5 +-
 requirements.txt                           | Bin 364 -> 176 bytes
 scripts/docs-dev.ps1                       |  18 +++
 scripts/generate-index-list.sh             | 135 +++++++++++++++++++++
 24 files changed, 523 insertions(+), 7 deletions(-)
 create mode 100644 docs/for-users/commands/.index-template.md
 create mode 100644 docs/for-users/commands/alias.md
 create mode 100644 docs/for-users/commands/clear.md
 create mode 100644 docs/for-users/commands/ignore.md
 create mode 100644 docs/for-users/commands/index.md
 create mode 100644 docs/for-users/commands/join.md
 create mode 100644 docs/for-users/commands/leave.md
 create mode 100644 docs/for-users/commands/parse.md
 create mode 100644 docs/for-users/commands/reset-title.md
 create mode 100644 docs/for-users/commands/save-title.md
 create mode 100644 docs/for-users/commands/speak.md
 create mode 100644 docs/for-users/commands/title.md
 create mode 100644 docs/for-users/commands/vcspeaker.md
 create mode 100644 docs/for-users/commands/voice.md
 create mode 100644 docs/for-users/features/.index-template.md
 create mode 100644 docs/for-users/features/alias.md
 create mode 100644 docs/for-users/features/index.md
 create mode 100644 docs/for-users/features/title.md
 create mode 100644 scripts/docs-dev.ps1
 create mode 100644 scripts/generate-index-list.sh

diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
index 8d92c955..0c7c0353 100644
--- a/.github/workflows/mkdocs.yml
+++ b/.github/workflows/mkdocs.yml
@@ -1,13 +1,15 @@
-name: 📚 Deploy MkDocs
+name: 📚 Build & Deploy MkDocs
 on:
   push:
     branches:
       - main
+  pull_request:
+  merge_group:
 
-jobs: 
+jobs:
   build:
     runs-on: ubuntu-latest
-    
+
     steps:
       - name: 📥 Checkout ${{ github.repository }}
         uses: actions/checkout@v4
@@ -15,14 +17,23 @@ jobs:
       - name: 🐍 Setup Python 3.10
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: "3.10"
 
       - name: 📄 Install Material for MkDocs
         run: pip install -r requirements.txt
-        
+
+      - name: Generate list
+        run: |
+          chmod +x ./scripts/generate-index-list.sh
+          ./scripts/generate-index-list.sh
+
+          # 差分があればエラー
+          git config core.filemode false
+          git diff --exit-code
+
       - name: 🏗️ Build MkDocs
         run: python -m mkdocs build --verbose --clean --strict
-      
+
       - name: 📤 Upload Pages Artifact
         uses: actions/upload-pages-artifact@v3
         with:
@@ -30,6 +41,7 @@ jobs:
 
   deploy:
     runs-on: ubuntu-latest
+    if: github.event_name == 'push'
     needs: build
     permissions:
       pages: write
diff --git a/.gitignore b/.gitignore
index a0062d99..cf3cf952 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 .gradle
 .idea
+.venv
 build
 
 store/
diff --git a/docs/for-users/commands/.index-template.md b/docs/for-users/commands/.index-template.md
new file mode 100644
index 00000000..fed84675
--- /dev/null
+++ b/docs/for-users/commands/.index-template.md
@@ -0,0 +1,3 @@
+# コマンド一覧
+
+<!-- COMMANDS -->
diff --git a/docs/for-users/commands/alias.md b/docs/for-users/commands/alias.md
new file mode 100644
index 00000000..140b8c1f
--- /dev/null
+++ b/docs/for-users/commands/alias.md
@@ -0,0 +1,55 @@
+# alias
+
+エイリアスに関する操作を行えます。
+
+## 使い方
+
+エイリアスに関する操作を行うには、以下のコマンドを使用します。
+
+### エイリアスの作成
+
+エイリアスを作成します。
+
+```text
+/alias create <タイプ> <検索文字列> <置換文字列>
+```
+
+- `<タイプ>`: エイリアスの種類を指定します。利用可能な種類は `Text`、`Regex`、`Emoji` です。
+- `<検索文字列>`: 置き換える条件となる文字列を指定します。
+- `<置換文字列>`: 検索文字列にマッチした場合に置き換える文字列を指定します。
+
+### エイリアスの更新
+
+既存のエイリアスを更新します。
+
+```text
+/alias update <エイリアス> [<新しいタイプ>] [<新しい検索文字列>] [<新しい置換文字列>]
+```
+
+- `<エイリアス>`: 更新するエイリアスを指定します。
+- `<新しいタイプ>`: 新しいエイリアスの種類を指定します（オプション）。
+- `<新しい検索文字列>`: 新しい検索文字列を指定します（オプション）。
+- `<新しい置換文字列>`: 新しい置換文字列を指定します（オプション）。
+
+### エイリアスの削除
+
+エイリアスを削除します。
+
+```text
+/alias delete <エイリアス>
+```
+
+- `<エイリアス>`: 削除するエイリアスを指定します。
+
+### エイリアスの一覧表示
+
+設定されているエイリアスの一覧を表示します。
+
+```text
+/alias list
+```
+
+
+## 関連するページ
+
+- [Alias 機能について](../features/alias.md)
diff --git a/docs/for-users/commands/clear.md b/docs/for-users/commands/clear.md
new file mode 100644
index 00000000..059fa4aa
--- /dev/null
+++ b/docs/for-users/commands/clear.md
@@ -0,0 +1,12 @@
+# clear
+
+予定されているメッセージの読み上げを中止します。  
+ボイスチャンネルに参加している際に、これまでに予定されていた全てのメッセージの読み上げを停止させることができます。
+
+## 使い方
+
+`/clear` コマンドを実行します。
+
+## 注意事項
+
+- このコマンドは、VCに参加しているユーザーのみが使用できます。
diff --git a/docs/for-users/commands/ignore.md b/docs/for-users/commands/ignore.md
new file mode 100644
index 00000000..bb9a4b26
--- /dev/null
+++ b/docs/for-users/commands/ignore.md
@@ -0,0 +1,41 @@
+# ignore
+
+無視ルールを設定します。無視対象のメッセージが投稿されても、読み上げられないようになります。
+
+## 使い方
+
+### 無視ルールの作成
+
+無視ルールを作成します。  
+このコマンドを使用すると、特定の文字列を含む、または完全一致するメッセージを読み上げないように設定できます。
+
+```text
+/ignore create <無視判定の種類> <無視する文字列>
+```
+
+- `<無視判定の種類>`: 無視判定の種類 (`Contains` または `Exact`)。`Contains` は指定した文字列を含む場合、`Exact` は完全に一致する場合に無視
+- `<無視する文字列>`: 含む場合、または完全一致する場合に無視する文字列
+
+### 無視の削除
+
+設定された無視ルールを削除します。
+
+```text
+/ignore delete <text>
+```
+
+**引数**:
+
+- `text`: 対象の無視する文字列
+
+### List
+
+設定されている無視ルールの一覧を表示します。
+
+```text
+/ignore list
+```
+
+## 注意事項
+
+- 無視ルールの設定は、サーバーごとに適用されます。他のサーバーで設定した無視ルールは影響しません。
diff --git a/docs/for-users/commands/index.md b/docs/for-users/commands/index.md
new file mode 100644
index 00000000..624dbf7d
--- /dev/null
+++ b/docs/for-users/commands/index.md
@@ -0,0 +1,14 @@
+# コマンド一覧
+
+- [alias](alias.md): エイリアスに関する操作を行えます。
+- [clear](clear.md): 予定されているメッセージの読み上げを中止します。
+- [ignore](ignore.md): 無視ルールを設定します。無視対象のメッセージが投稿されても、読み上げられないようになります。
+- [join](join.md): Bot をボイスチャンネルに接続させます。
+- [leave](leave.md): ボイスチャンネルから退出します。
+- [parse](parse.md): 読み上げる文章の処理をテストします。
+- [reset-title](reset-title.md): ボイスチャンネルのチャンネル名（タイトル）をリセットします。
+- [save-title](save-title.md): 現在のチャンネル名をタイトルとして保存します。
+- [speak](speak.md): VCSpeaker として文章を読み上げます (デバッグ用)。
+- [title](title.md): ボイスチャンネルのチャンネル名を一時的に変更します。
+- [vcspeaker](vcspeaker.md): VCSpeaker を操作するためのコマンドです。
+- [voice](voice.md): 自分が投稿したメッセージの読み上げ音声の設定を行うためのコマンドです。
diff --git a/docs/for-users/commands/join.md b/docs/for-users/commands/join.md
new file mode 100644
index 00000000..0296140e
--- /dev/null
+++ b/docs/for-users/commands/join.md
@@ -0,0 +1,20 @@
+# join
+
+Bot をボイスチャンネルに接続させます。
+
+## 使い方
+
+このコマンドは、Bot をボイスチャンネルに接続させます。AFK チャンネルへの接続は拒否されます。  
+Bot が既に他のボイスチャンネルにいる場合、そのチャンネルに移動します。
+
+```text
+/join [channel]
+```
+
+- `[channel]`: 参加する VC。指定しない場合、コマンドを実行したユーザーの現在のボイスチャンネルに接続します。
+
+## 注意事項
+
+- AFK チャンネルには接続できません
+- ユーザーがボイスチャンネルに参加していない場合、コマンドは失敗します
+- ボットが既にボイスチャンネルにいる場合、指定されたチャンネルに移動します
diff --git a/docs/for-users/commands/leave.md b/docs/for-users/commands/leave.md
new file mode 100644
index 00000000..b300a1cc
--- /dev/null
+++ b/docs/for-users/commands/leave.md
@@ -0,0 +1,16 @@
+# leave
+
+ボイスチャンネルから退出します。
+
+## 使い方
+
+このコマンドは、Bot が現在参加しているボイスチャンネルから退出するために使用します。
+
+```text
+/leave
+/disconnect
+```
+
+## 注意事項
+
+- Bot がいずれかのボイスチャンネルに参加していない場合、エラーになります。
diff --git a/docs/for-users/commands/parse.md b/docs/for-users/commands/parse.md
new file mode 100644
index 00000000..f29623bb
--- /dev/null
+++ b/docs/for-users/commands/parse.md
@@ -0,0 +1,17 @@
+# parse
+
+読み上げる文章の処理をテストします。
+
+## 使い方
+
+ユーザーが指定したメッセージに対して、無視ルールの確認、エイリアスの適用、絵文字の置き換えなどの処理を行い、その結果を表示します。
+
+```text
+/parse <message>
+```
+
+- `<message>`: 処理をテストするメッセージ
+
+## 注意事項
+
+- メッセージに含まれる無視ルール、エイリアス、絵文字の置き換えは、サーバごとに設定されたルールに基づいて行われます。
diff --git a/docs/for-users/commands/reset-title.md b/docs/for-users/commands/reset-title.md
new file mode 100644
index 00000000..151ecc75
--- /dev/null
+++ b/docs/for-users/commands/reset-title.md
@@ -0,0 +1,19 @@
+# reset-title
+
+ボイスチャンネルのチャンネル名（タイトル）をリセットします。
+
+## 使い方
+
+指定されたボイスチャンネルのチャンネル名をリセットします。  
+ユーザーがボイスチャンネルにいる場合、そのチャンネルのチャンネル名がリセットされます。  
+指定されたチャンネルがない場合は、ユーザーが現在参加しているボイスチャンネルのチャンネル名がリセットされます。
+
+```text
+/reset-title [channel]
+```
+
+- `[channel]`: タイトルをリセットするチャンネル
+
+## 注意事項
+
+- チャンネル名が即時に更新されない場合があります。これは Discord のレートリミットによるもので、しばらく待つことで反映されます。
diff --git a/docs/for-users/commands/save-title.md b/docs/for-users/commands/save-title.md
new file mode 100644
index 00000000..e9a78ef7
--- /dev/null
+++ b/docs/for-users/commands/save-title.md
@@ -0,0 +1,28 @@
+# save-title
+
+現在のチャンネル名をタイトルとして保存します。
+
+## 使い方
+
+### 全てのチャンネルのタイトルを保存
+
+全てのボイスチャンネルのタイトルを保存し、成功した場合はそれぞれのチャンネル名と保存されたタイトルを表示します。
+
+```text
+/save-title all
+```
+
+### 指定されたチャンネルのタイトルを保存します
+
+指定されたボイスチャンネルのタイトルを保存し、成功した場合はそのチャンネル名と保存されたタイトルを表示します。
+
+```text
+/save-title channel [channel]
+```
+
+- `[channel]`: タイトルを保存するチャンネル。指定しない場合は、コマンドを実行したユーザーがいるチャンネルが選択されます。
+
+## 注意事項
+
+- サーバにおいて、一度でもタイトルを設定したことが無い場合、このコマンドは失敗します。
+  [title コマンド](title.md) を用いてタイトルを設定したうえで利用してください。
diff --git a/docs/for-users/commands/speak.md b/docs/for-users/commands/speak.md
new file mode 100644
index 00000000..6ce82c21
--- /dev/null
+++ b/docs/for-users/commands/speak.md
@@ -0,0 +1,11 @@
+# speak
+
+VCSpeaker として文章を読み上げます (デバッグ用)。
+
+## 使い方
+
+```text
+/speak <text>
+```
+
+- `<text>`: 読み上げる文章
diff --git a/docs/for-users/commands/title.md b/docs/for-users/commands/title.md
new file mode 100644
index 00000000..be1aa406
--- /dev/null
+++ b/docs/for-users/commands/title.md
@@ -0,0 +1,25 @@
+# title
+
+ボイスチャンネルのチャンネル名を一時的に変更します。
+
+## 使い方
+
+タイトルを設定します。  
+指定したチャンネル、またはユーザーが現在参加しているボイスチャンネルのタイトルを変更します。  
+チャンネルから全員が退出すると、タイトルはリセットされます。
+
+```text
+/title <title> [channel]
+```
+
+- `<title>`: 設定するタイトル
+- `[channel]`: タイトルを設定するチャンネル。指定しない場合は、コマンドを実行したユーザーが現在参加しているボイスチャンネルが対象になります。
+
+## 注意事項
+
+- チャンネル名の変更にはレートリミットが適用されるため、名前が反映されるまでに時間がかかる場合があります。
+- チャンネルから全員が退出すると、設定したタイトルはリセットされます。
+
+## 関連するページ
+
+- [Title 機能について](../features/title.md)
diff --git a/docs/for-users/commands/vcspeaker.md b/docs/for-users/commands/vcspeaker.md
new file mode 100644
index 00000000..86339148
--- /dev/null
+++ b/docs/for-users/commands/vcspeaker.md
@@ -0,0 +1,37 @@
+# vcspeaker
+
+VCSpeaker を操作するためのコマンドです。  
+このコマンドを使用して、テキストチャンネルの読み上げ設定や、Bot の再起動などを行うことができます。
+
+## 使い方
+
+### restart
+
+VCSpeaker を再起動します。
+
+```text
+/vcspeaker restart
+```
+
+### settings
+
+VCSpeaker の設定を行います。この設定は、サーバごとに保存されます。
+
+```text
+/vcspeaker settings [channel] [prefix] [speaker] [emotion] [emotion-level] [pitch] [speed] [volume] [auto-join]
+```
+
+- `[channel]`: 読み上げるテキストチャンネル
+- `[prefix]`: チャットコマンドのプレフィックス
+- `[speaker]`: 話者
+- `[emotion]`: 感情
+- `[emotion-level]`: 感情レベル (1 から 4)
+- `[pitch]`: ピッチ (50% から 200%)
+- `[speed]`: 速度 (50% から 200%)
+- `[volume]`: 音量 (50% から 200%)
+- `[auto-join]`: ボイスチャンネルに自動で入退室するかどうか
+
+## 注意事項
+
+- `restart` サブコマンドを使用すると、Bot は即座に再起動されます。これにより、一時的に Bot が使用不可能になることがあります。
+- `settings` サブコマンドで設定を変更する際、指定しなかったオプションは現在の設定を維持します。全ての設定を一度に変更する必要はありません。
diff --git a/docs/for-users/commands/voice.md b/docs/for-users/commands/voice.md
new file mode 100644
index 00000000..9261d6b6
--- /dev/null
+++ b/docs/for-users/commands/voice.md
@@ -0,0 +1,34 @@
+# voice
+
+自分が投稿したメッセージの読み上げ音声の設定を行うためのコマンドです。  
+話者、感情、感情レベル、ピッチ、速度、音量をカスタマイズできます。
+
+## 使い方
+
+### 自分の声を設定
+
+自分の声の設定を行います。  
+話者、感情、感情レベル、ピッチ、速度、音量を指定してカスタマイズできます。
+
+```text
+/voice set [speaker] [emotion] [emotion-level] [pitch] [speed] [volume]
+```
+
+- `[speaker]`: 話者を指定します。利用可能な話者はコマンドのオプションで確認できます。
+- `[emotion]`: 感情を指定します。利用可能な感情はコマンドのオプションで確認できます。`なし` を指定することもできます。
+- `[emotion-level]`: 感情レベルを 1 から 4 の間で指定します。感情が `なし` の場合は指定不要です。
+- `[pitch]`: ピッチを 50% から 200% の間で指定します。
+- `[speed]`: 速度を 50% から 200% の間で指定します。
+- `[volume]`: 音量を 50% から 200% の間で指定します。
+
+### 自分の声を初期化
+
+自分の声の設定を初期化します。設定されていたカスタマイズがすべてリセットされます。
+
+```text
+/voice reset
+```
+
+## 注意事項
+
+- 自分の声の設定は、おなじ VCSpeaker.kt の Bot であればサーバを問わず設定されます。
diff --git a/docs/for-users/features/.index-template.md b/docs/for-users/features/.index-template.md
new file mode 100644
index 00000000..6f2e06af
--- /dev/null
+++ b/docs/for-users/features/.index-template.md
@@ -0,0 +1,3 @@
+# 機能一覧
+
+<!-- COMMANDS -->
diff --git a/docs/for-users/features/alias.md b/docs/for-users/features/alias.md
new file mode 100644
index 00000000..b8cfed0e
--- /dev/null
+++ b/docs/for-users/features/alias.md
@@ -0,0 +1,4 @@
+# エイリアス
+
+VCSpeaker.kt では、特定の文字列を置き換えて読み上げる「エイリアス」という機能があります。  
+この機能を用いることで、不適切な発言を伏せたり、サーバ絵文字を見た目通りに読み上げさせることができます。
diff --git a/docs/for-users/features/index.md b/docs/for-users/features/index.md
new file mode 100644
index 00000000..aa8c97ac
--- /dev/null
+++ b/docs/for-users/features/index.md
@@ -0,0 +1,4 @@
+# 機能一覧
+
+- [alias](alias.md): VCSpeaker.kt では、特定の文字列を置き換えて読み上げる「エイリアス」という機能があります。
+- [title](title.md): VCSpeaker.kt では、ボイスチャンネルのチャンネル名を一時的に変更することができ、この機能を「タイトル」と呼んでいます。
diff --git a/docs/for-users/features/title.md b/docs/for-users/features/title.md
new file mode 100644
index 00000000..db027253
--- /dev/null
+++ b/docs/for-users/features/title.md
@@ -0,0 +1,4 @@
+# タイトル
+
+VCSpeaker.kt では、ボイスチャンネルのチャンネル名を一時的に変更することができ、この機能を「タイトル」と呼んでいます。  
+この機能を用いることで、ボイスチャンネルでなにをしているかを周りに知らせることができたりできます。
diff --git a/docs/for-users/index.md b/docs/for-users/index.md
index ff8f707d..519f5843 100644
--- a/docs/for-users/index.md
+++ b/docs/for-users/index.md
@@ -1 +1,4 @@
-# :material-book: 利用者ガイド
\ No newline at end of file
+# :material-book: 利用者ガイド
+
+- [commands](commands/): コマンドについての説明
+- [features](features/): VCSpeaker.kt の独自機能の説明
diff --git a/requirements.txt b/requirements.txt
index fe455550c3149d4189ad80e87bf90e219422a18f..ae87ad7a6d6273f1ba4b6ca5b9f5f441a18ee3cb 100644
GIT binary patch
literal 176
zcmZ9GK@Nj33<U4}i!BIn;NZuk#7eC?F(PS;`uYMA9D3Z*j&{>C*i?vG9I(5kBZ2>L
zvBWU@$OUG7Mae`CM|5W;N`-~rQp7R@Um4UUukz(^2`xHoE<q(e>fKhN20QFeo;G(8
TuS6sEIQ(PawQ}B9j+5>O?7ci~

literal 364
zcma)&%MOAt5Jm6W#80Wg0t**@3<^Oa4+DzCk5|t$#z(@!G&h}2=RVrUz0py*I_))R
z%UWxt6vSF;q3>I#Oji}mb@U54o#>RIV|A?yr%G+m@n~#-pV6_YGyERzNIifKo+C-d
zjcL~*Q^sEDMkfz`zaEy=e4<$oW0pFgw?k_RsUoIhkjyZemv;}(eC;>v1qn$1n0KU{
NLi+aoqR*dtJpuc{KC1u#

diff --git a/scripts/docs-dev.ps1 b/scripts/docs-dev.ps1
new file mode 100644
index 00000000..04627619
--- /dev/null
+++ b/scripts/docs-dev.ps1
@@ -0,0 +1,18 @@
+$oldErrorActionPreference = $ErrorActionPreference
+$ErrorActionPreference = "stop"
+
+Set-Location $PSScriptRoot
+Set-Location ..
+
+# check exists venv
+if (!(Test-Path -Path .venv)) {
+  python3 -mvenv .venv
+}
+
+# activate venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+
+mkdocs serve --dev-addr=0.0.0.0:8080
+
+$ErrorActionPreference = $oldErrorActionPreference
\ No newline at end of file
diff --git a/scripts/generate-index-list.sh b/scripts/generate-index-list.sh
new file mode 100644
index 00000000..44a6cf5a
--- /dev/null
+++ b/scripts/generate-index-list.sh
@@ -0,0 +1,135 @@
+#!/bin/bash
+
+# /docs/for-users/commands/ にあるコマンドの一覧を生成する
+# テンプレートとして /docs/for-users/commands/.index-template.md を使用し、<!-- COMMANDS --> に一覧を挿入する
+# 一覧は箇条書きで、コマンド名を表示する
+
+# 一覧を生成する対象のディレクトリ
+DIRS=(
+  "docs/for-users/commands"
+  "docs/for-users/features"
+)
+
+# テンプレートファイル
+TEMPLATE_FILENAME=".index-template.md"
+
+# 出力先のディレクトリ
+OUTPUT_DIR="docs/for-users"
+
+# 一覧を挿入する箇所
+MARKER='<!-- COMMANDS -->'
+
+# Markdown description を生成する
+# 引数: Markdownファイルのパス
+get_description() {
+  # description: から始まる行を抽出し、description: を削除する
+  local description=$(cat $1 | grep '^description:' | sed -e 's/description://g')
+  echo $description
+}
+
+# front matter を無視して1行目を取得する
+# 引数: Markdownファイルのパス
+get_first_line() {
+  local file="$1"
+
+  # front matter をすでに見つけている
+  local found_front_matter=0
+  # front matter の中にいる
+  local in_front_matter=0
+  # h1 をすでに見つけている
+  local after_h1=0
+
+  while IFS= read -r line; do
+    # front matter
+    if [ "$line" = "---" ]; then
+      if [ $found_front_matter -eq 0 ]; then
+        # front matter を見つけた
+        found_front_matter=1
+        in_front_matter=1
+        continue
+      fi
+
+      # front matter の終わり
+      in_front_matter=0
+      continue
+    fi
+
+    # front matter の中にいる
+    if [ $in_front_matter -eq 1 ]; then
+      continue
+    fi
+
+    # front matter を見つけていて、その次の行
+    if [ $found_front_matter -eq 1 ] && [ -n "$line" ]; then
+      trim_line=$(echo $line | sed -e 's/^[[:space:]]*//')
+      if [ -n "$trim_line" ]; then
+        echo "$trim_line"
+        return
+      fi
+    fi
+
+    # h1 をすでに見つけている
+    if [ $after_h1 -eq 1 ] && [ -n "$line" ]; then
+      trim_line=$(echo $line | sed -e 's/^[[:space:]]*//')
+      if [ -n "$trim_line" ]; then
+        echo "$trim_line"
+        return
+      fi
+    fi
+
+    # h1 を見つけた
+    if [ "${line:0:2}" = "# " ]; then
+      after_h1=1
+      continue
+    fi
+  done < "$file"
+
+  # ファイルの最後まで検索しても見つからなかった場合
+  echo ""
+}
+
+# 一覧を生成する
+# 引数: 一覧を生成する対象のディレクトリ
+generate_list() {
+  local dir=$1
+  #local list=$(ls $dir | grep -v $TEMPLATE_FILENAME | sed -e 's/\.md//g')
+  local list=$(find $dir -maxdepth 1 -type f -name '*.md' | grep -v $TEMPLATE_FILENAME | grep -v 'index.md' | sed -e 's/\.md//g' | sed -e 's/.*\///g' | sort)
+  local result=''
+  for item in $list; do
+    local description=$(get_description "$dir/$item.md")
+    if [ -n "$description" ]; then
+      result="$result- [$item]($item.md) - $description\n"
+      continue
+    fi
+    local first_line=$(get_first_line "$dir/$item.md")
+    if [ -n "$first_line" ]; then
+      result="$result- [$item]($item.md): $first_line\n"
+      continue
+    fi
+
+    result="$result- [$item]($item.md)\n"
+  done
+  echo -e "$result"
+}
+
+# 一覧を生成する
+# 引数: 一覧を挿入する箇所
+generate() {
+  local marker=$*
+  for dir in "${DIRS[@]}"; do
+    local template="$dir/$TEMPLATE_FILENAME"
+    local output="$OUTPUT_DIR/$(basename $dir)/index.md"
+    local list=$(generate_list $dir)
+  
+    # 一覧を一時ファイルに書き出す
+    local tmpfile=$(mktemp)
+    echo "$list" > $tmpfile
+
+    # 一覧を挿入する
+    cp $template $output
+    sed -i -e "/$marker/r $tmpfile" -e "/$marker/d" $output
+  done
+}
+
+# 一覧を生成する
+generate $MARKER