README.ja.md

TOC Generator

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

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

Table of Contents

Details

• インストール
• スクリーンショット
• オプション
  • 個別に指定
• Action イベント詳細
  • 対象イベント
  • Conditions
• 補足
  • GITHUB_TOKEN
  • プルリクエストの作成
  • Context variables
  • Context PR variables
• 設定例
  • 例１
  • 例２
  • 例３
• このアクションを使用しているリポジトリの例
• Author

インストール

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

   <!-- START doctoc -->
   <!-- END doctoc -->

   詳細
2. workflow を設定
   例：.github/workflows/toc.yml

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

スクリーンショット

オプション

name	description	default	required	e.g.
TARGET_PATHS	対象のファイルパス (カンマ区切り, 詳細)	README*.md	true	README*.md,CHANGELOG.md, .
TOC_TITLE	目次タイトル	**Table of Contents**		''
MAX_HEADER_LEVEL	Heading最大レベル (詳細)			3
CUSTOM_MODE	Customモードかどうか(生成例)	false		true
CUSTOM_TEMPLATE	Customテンプレート(Customモード)	<p align="center">${ITEMS}</p>
ITEM_TEMPLATE	アイテムテンプレート(Customモード)	<a href="${LINK}">${TEXT}</a>
SEPARATOR	セパレータ(Customモード)	<span>|</span>
FOLDING	目次を折りたたみ式にするかどうか	false		true
COMMIT_MESSAGE	コミットメッセージ	chore(docs): update TOC	true	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/	true
PR_BRANCH_NAME	プルリクエストのブランチ名 Context variables	update-toc-${PR_ID}	true	toc-${PR_NUMBER}
PR_TITLE	プルリクエストのタイトル Context variables	chore(docs): update TOC (${PR_MERGE_REF})	true	docs: update TOC
PR_BODY	プルリクエストの本文 Context PR variables	action.yml	true
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以外のため)	<!-- toc
CLOSING_COMMENT	終了コメント (DocToc以外のため)	<!-- tocstop
GITHUB_TOKEN	アクセストークン	${{github.token}}	true	${{secrets.ACCESS_TOKEN}}

個別に指定

doctoc に使用されているオプションはコメントで値を指定することが可能です。
異なる設定で複数の目次を生成したい場合は以下のように個別に値を指定してください。

例：

<!-- START doctoc -->
<!-- param::isNotitle::true:: -->
<!-- param::isCustomMode::true:: -->

<!-- END doctoc -->

...

Action イベント詳細

対象イベント

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

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

Conditions

condition1

• ブランチへのプッシュ (タグのプッシュではない)
  • ブランチ名 (TARGET_BRANCH_PREFIX)

condition2

• 指定したラベルが付与されているかどうか (INCLUDE_LABELS)
• ブランチ名 (TARGET_BRANCH_PREFIX)

補足

GITHUB_TOKEN

GitHub Actions で提供されるGITHUB_TOKENは連続するイベントを作成する権限がありません。
したがって、プッシュによってトリガーされるビルドアクションなどは実行されません。

これはブランチプロテクションを設定していると問題になる場合があります。

もしアクションをトリガーしたい場合は代わりにpersonal access tokenを使用してください。

1. public_repo または repo の権限で Personal access token を生成
   (repo はプライベートリポジトリで必要です)
2. ACCESS_TOKENとして保存
3. GITHUB_TOKENの代わりにACCESS_TOKENを使用するように設定
   例：.github/workflows/toc.yml

   on: push
   name: TOC Generator
   jobs:
     generateTOC:
       name: TOC Generator
       runs-on: ubuntu-latest
       steps:
         - uses: technote-space/toc-generator@v3
           with:
             GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}

プルリクエストの作成

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

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

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

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@v3

Context variables

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 (例：master)
PR_MERGE_REF	pull_request.base.ref (例：change -> master)
PR_TITLE	pull_request.title (例：update the README with new information.)

Payload example

Context PR variables

• Context variables

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

設定例

例１

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

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

例２

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

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@v3
        with:
          CREATE_PR: true
          TARGET_BRANCH_PREFIX: release/

例３

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

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

このアクションを使用しているリポジトリの例

• Release GitHub Actions
  • toc.yml
• Auto card labeler
  • toc.yml
• Assign Author
  • toc.yml
• TOC Generator
  • toc.yml
• Package Version Check Action
  • toc.yml
• jina-ai/jina Change Log
  • autocommit.yml

Author

GitHub (Technote)
Blog