GitHub Action to generate TOC.
npm install @technote-space/toc-generator



Read this in other languages: English, 日本語.
これは目次を生成するGitHub Actionsです。
DocToc を実行し変更があればコミットします。
Details
- インストール
- スクリーンショット
- オプション
- 個別に指定
- Action イベント詳細
- 対象イベント
- Conditions
- 補足
- GITHUB_TOKEN
- プルリクエストの作成
- Context variables
- Context PR variables
- 設定例
- 例1
- 例2
- 例3
- Author
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最大レベル (詳細)| |3|
|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以外のため)|...
`
- 次のアクティビティタイプは明示的に指定する必要があります。 (詳細)
- labeled, unlabeled, closedTARGET_BRANCH_PREFIX$3
#### condition1
- ブランチへのプッシュ (タグのプッシュではない)
- ブランチ名 ()INCLUDE_LABELS
#### condition2
- 指定したラベルが付与されているかどうか ()TARGET_BRANCH_PREFIX
- ブランチ名 ()
は連続するイベントを作成する権限がありません。
したがって、プッシュによってトリガーされるビルドアクションなどは実行されません。 これはブランチプロテクションを設定していると問題になる場合があります。
もしアクションをトリガーしたい場合は代わりに
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
`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 (例:11) |
| 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.) |$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を作成または更新`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
with:
CREATE_PR: true
TARGET_BRANCH_PREFIX: release/
`$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
``