TOC Generator

![CI Status](https://github.com/technote-space/toc-generator/actions)
![codecov](https://codecov.io/gh/technote-space/toc-generator)
![CodeFactor](https://www.codefactor.io/repository/github/technote-space/toc-generator)
![License: MIT](https://github.com/technote-space/toc-generator/blob/main/LICENSE)

Read this in other languages: English, 日本語.

これは目次を生成するGitHub Actionsです。
DocToc を実行し変更があればコミットします。

Details

- インストール
- スクリーンショット
- オプション
- 個別に指定
- Action イベント詳細
- 対象イベント
- Conditions
- 補足
- GITHUB_TOKEN
- プルリクエストの作成
- Context variables
- Context PR variables
- 設定例
- 例１
- 例２
- 例３
- Author

インストール

1. 目次の位置を指定 (option)
``

markdown


   詳細  
1. workflow を設定  
   例：

.github/workflows/toc.yml

yaml
   on: push
   name: TOC Generator
   jobs:
     generateTOC:
       name: TOC Generator
       runs-on: ubuntu-latest
       steps:
         - uses: technote-space/toc-generator@v4


スクリーンショット

!behavior
オプション

| name | description | default | e.g. |
|:---|:---|:---|:---|
|TARGET_PATHS|対象のファイルパス (カンマ区切り, 詳細)|

README.md|README.md,CHANGELOG.md, .

|
|TOC_TITLE|目次タイトル|

Table of Contents|''

|
|MAX_HEADER_LEVEL|Heading最大レベル (詳細)| |

|
|CUSTOM_MODE|Customモードかどうか(生成例)|

false|true

|
|CUSTOM_TEMPLATE|Customテンプレート(Customモード)|

${ITEMS}

| |
|ITEM_TEMPLATE|アイテムテンプレート(Customモード)|

${TEXT}

| |
|SEPARATOR|セパレータ(Customモード)|\|\| |
|FOLDING|目次を折りたたみ式にするかどうか|

false|true

|
|COMMIT_MESSAGE|コミットメッセージ|

chore(docs): update TOC|docs: update TOC

|
|COMMIT_NAME|コミット時に設定する名前|

${github.actor}

| |
|COMMIT_EMAIL|コミット時に設定するメールアドレス|

${github.actor}@users.noreply.github.com

| |
|CREATE_PR|プルリクエストを作成するかどうか|

false|true

|
|CHECK_ONLY_DEFAULT_BRANCH|デフォルトのブランチのみをチェックするかどうか|

false|true

|
|PR_BRANCH_PREFIX|プルリクエストのブランチプリフィックス|

toc-generator/

| |
|PR_BRANCH_NAME|プルリクエストのブランチ名
Context variables|

update-toc-${PR_ID}|toc-${PR_NUMBER}

|
|PR_TITLE|プルリクエストのタイトル
Context variables|

chore(docs): update TOC (${PR_MERGE_REF})|docs: update TOC

|
|PR_BODY|プルリクエストの本文
Context PR variables|action.yml| |
|PR_COMMENT_BODY|プルリクエストの本文(コメント用)
Context PR variables|action.yml| |
|PR_CLOSE_MESSAGE|プルリクエストを閉じるときのメッセージ|

This PR has been closed because it is no longer needed.

| |
|TARGET_BRANCH_PREFIX|ブランチ名のフィルタ| |

release/

|
|INCLUDE_LABELS|プルリクエストに付与されているかチェックするラベル| |

Label1, Label2

|
|OPENING_COMMENT|開始コメント (DocToc以外のため)|

...

`Action イベント詳細`


$3

| eventName: action | condition |
|:---|:---|
|push: *|condition1|
|pull_request: \[opened, synchronize, reopened, labeled, unlabeled]|condition2|
|pull_request: \[closed]||
|schedule, repository_dispatch, workflow_dispatch||

- 次のアクティビティタイプは明示的に指定する必要があります。 (詳細) -labeled, unlabeled, closed

`$3`


#### condition1
- ブランチへのプッシュ (タグのプッシュではない)
  - ブランチ名 (

TARGET_BRANCH_PREFIX

)
#### condition2
- 指定したラベルが付与されているかどうか (

INCLUDE_LABELS

)
- ブランチ名 (

TARGET_BRANCH_PREFIX

)
補足

$3

GitHub Actions で提供される

GITHUB_TOKEN

は連続するイベントを作成する権限がありません。  
したがって、プッシュによってトリガーされるビルドアクションなどは実行されません。  
これはブランチプロテクションを設定していると問題になる場合があります。

もしアクションをトリガーしたい場合は代わりにpersonal access tokenを使用してください。 1. public_repo または repo の権限で Personal access token を生成 (repo はプライベートリポジトリで必要です) 1. ACCESS_TOKENとして保存 1.GITHUB_TOKENの代わりにACCESS_TOKENを使用するように設定例：.github/workflows/toc.yml`yaml on: push name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4 with: GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}`

`$3`

CREATE_PR に true を設定した場合は、プルリクエストが作成されます。

`yaml on: pull_request name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4 with: CREATE_PR: true`

!create pr

closedアクティビティタイプが設定されている場合、このアクションは不要になったプルリクエストを閉じます。

`yaml on: pull_request: types: [opened, synchronize, reopened, closed] name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4`

`$3`


| name | description |
|:---|:---|
| PR_NUMBER | pull_request.number (例：

) |
| PR_NUMBER_REF |

#${pull_request.number} (例：#11

) |
| PR_ID | pull_request.id (例：

21031067

) |
| PR_HEAD_REF | pull_request.head.ref (例：

change

) |
| PR_BASE_REF | pull_request.base.ref (例：

main

) |
| PR_MERGE_REF | pull_request.base.ref (例：

change -> main

) |
| PR_TITLE | pull_request.title (例：

update the README with new information.

) |
Payload example
$3

- Context variables

| name | description | |:---|:---| | PR_LINK | プルリクエストへのリンク | | COMMANDS_OUTPUT | TOC コマンドの結果 | | FILES_SUMMARY | 例：Changed 2 files| | FILES | 変更されたファイル一覧 |

`設定例`


$3

ブランチを制限しないでPush時にアクションを実行し直接コミット

`yaml on: push name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4`

`$3`

release/ から始まるブランチのみを対象にPull Request更新時に実行しPull Requestを作成または更新

`$3`


デフォルトブランチのみを対象にスケジュールでアクションを実行し直接コミット  
（他のワークフローの起動のために作成したTokenを使用）

`yaml on: schedule: - cron: "0 23 *" name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4 with: GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }} CHECK_ONLY_DEFAULT_BRANCH: true``

Author

GitHub (Technote)
Blog

TOC Generator

Read this in other languages: English, 日本語.

これは目次を生成するGitHub Actionsです。
DocToc を実行し変更があればコミットします。

Details

インストール

1. 目次の位置を指定 (option)
``

markdown


   詳細  
1. workflow を設定  
   例：

.github/workflows/toc.yml

yaml
   on: push
   name: TOC Generator
   jobs:
     generateTOC:
       name: TOC Generator
       runs-on: ubuntu-latest
       steps:
         - uses: technote-space/toc-generator@v4


スクリーンショット

!behavior
オプション

| name | description | default | e.g. |
|:---|:---|:---|:---|
|TARGET_PATHS|対象のファイルパス (カンマ区切り, 詳細)|

README.md|README.md,CHANGELOG.md, .

|
|TOC_TITLE|目次タイトル|

Table of Contents|''

|
|MAX_HEADER_LEVEL|Heading最大レベル (詳細)| |

|
|CUSTOM_MODE|Customモードかどうか(生成例)|

false|true

|
|CUSTOM_TEMPLATE|Customテンプレート(Customモード)|

${ITEMS}

| |
|ITEM_TEMPLATE|アイテムテンプレート(Customモード)|

${TEXT}

| |
|SEPARATOR|セパレータ(Customモード)|\|\| |
|FOLDING|目次を折りたたみ式にするかどうか|

false|true

|
|COMMIT_MESSAGE|コミットメッセージ|

chore(docs): update TOC|docs: update TOC

|
|COMMIT_NAME|コミット時に設定する名前|

${github.actor}

| |
|COMMIT_EMAIL|コミット時に設定するメールアドレス|

${github.actor}@users.noreply.github.com

| |
|CREATE_PR|プルリクエストを作成するかどうか|

false|true

|
|CHECK_ONLY_DEFAULT_BRANCH|デフォルトのブランチのみをチェックするかどうか|

false|true

|
|PR_BRANCH_PREFIX|プルリクエストのブランチプリフィックス|

toc-generator/

| |
|PR_BRANCH_NAME|プルリクエストのブランチ名
Context variables|

update-toc-${PR_ID}|toc-${PR_NUMBER}

|
|PR_TITLE|プルリクエストのタイトル
Context variables|

chore(docs): update TOC (${PR_MERGE_REF})|docs: update TOC

|
|PR_BODY|プルリクエストの本文
Context PR variables|action.yml| |
|PR_COMMENT_BODY|プルリクエストの本文(コメント用)
Context PR variables|action.yml| |
|PR_CLOSE_MESSAGE|プルリクエストを閉じるときのメッセージ|

This PR has been closed because it is no longer needed.

| |
|TARGET_BRANCH_PREFIX|ブランチ名のフィルタ| |

release/

|
|INCLUDE_LABELS|プルリクエストに付与されているかチェックするラベル| |

Label1, Label2

|
|OPENING_COMMENT|開始コメント (DocToc以外のため)|

...

`Action イベント詳細`


$3

| eventName: action | condition |
|:---|:---|
|push: *|condition1|
|pull_request: \[opened, synchronize, reopened, labeled, unlabeled]|condition2|
|pull_request: \[closed]||
|schedule, repository_dispatch, workflow_dispatch||

- 次のアクティビティタイプは明示的に指定する必要があります。 (詳細) -labeled, unlabeled, closed

`$3`


#### condition1
- ブランチへのプッシュ (タグのプッシュではない)
  - ブランチ名 (

TARGET_BRANCH_PREFIX

)
#### condition2
- 指定したラベルが付与されているかどうか (

INCLUDE_LABELS

)
- ブランチ名 (

TARGET_BRANCH_PREFIX

)
補足

$3

GitHub Actions で提供される

GITHUB_TOKEN

は連続するイベントを作成する権限がありません。  
したがって、プッシュによってトリガーされるビルドアクションなどは実行されません。  
これはブランチプロテクションを設定していると問題になる場合があります。

`$3`

CREATE_PR に true を設定した場合は、プルリクエストが作成されます。

`yaml on: pull_request name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4 with: CREATE_PR: true`

!create pr

closedアクティビティタイプが設定されている場合、このアクションは不要になったプルリクエストを閉じます。

`$3`


| name | description |
|:---|:---|
| PR_NUMBER | pull_request.number (例：

) |
| PR_NUMBER_REF |

#${pull_request.number} (例：#11

) |
| PR_ID | pull_request.id (例：

21031067

) |
| PR_HEAD_REF | pull_request.head.ref (例：

change

) |
| PR_BASE_REF | pull_request.base.ref (例：

main

) |
| PR_MERGE_REF | pull_request.base.ref (例：

change -> main

) |
| PR_TITLE | pull_request.title (例：

update the README with new information.

) |
Payload example
$3

- Context variables

`設定例`


$3

ブランチを制限しないでPush時にアクションを実行し直接コミット

`yaml on: push name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4`

`$3`

release/ から始まるブランチのみを対象にPull Request更新時に実行しPull Requestを作成または更新

`$3`


デフォルトブランチのみを対象にスケジュールでアクションを実行し直接コミット  
（他のワークフローの起動のために作成したTokenを使用）

Author

GitHub (Technote)
Blog

@technote-space/toc-generator

TOC Generator

Table of Contents

インストール

スクリーンショット

オプション

`Action イベント詳細`

$3

`$3`

補足

$3

`$3`

`$3`

$3

`設定例`

$3

`$3`

`$3`

Author

@technote-space/toc-generator

TOC Generator

Table of Contents

インストール

スクリーンショット

オプション

`Action イベント詳細`

$3

`$3`

補足

$3

`$3`

`$3`

$3

`設定例`

$3

`$3`

`$3`

Author