TOC Generator
Read this in other languages: English, 日本語.
This is a GitHub Actions
to generate TOC (Table of Contents),
which executes DocToc and commits if changed.
Table of Contents
Details
Installation
- Specify location of TOC (option)
e.g.README.md
detail<!-- START doctoc --> <!-- END doctoc -->
- Setup workflow
e.g..github/workflows/toc.yml
on: push name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4
Screenshot
Options
name | description | default | e.g. |
---|---|---|---|
TARGET_PATHS | Target file path. (Comma separated, Detail) | README*.md |
README*.md,CHANGELOG.md , . |
TOC_TITLE | TOC Title | **Table of Contents** |
'' |
MAX_HEADER_LEVEL | Maximum heading level. (Detail) | 3 |
|
CUSTOM_MODE | Whether it is custom mode(Generated Example) | false |
true |
CUSTOM_TEMPLATE | Custom template for custom mode | <p align="center">${ITEMS}</p> |
|
ITEM_TEMPLATE | Item template for custom mode | <a href="${LINK}">${TEXT}</a> |
|
SEPARATOR | Separator for custom mode | <span>|</span> |
|
FOLDING | Whether to make TOC foldable | false |
true |
COMMIT_MESSAGE | Commit message | chore(docs): update TOC |
docs: update TOC |
COMMIT_NAME | Git commit name | ${github.actor} |
|
COMMIT_EMAIL | Git commit email | ${github.actor}@users.noreply.github.com |
|
CREATE_PR | Whether to create PullRequest | false |
true |
CHECK_ONLY_DEFAULT_BRANCH | Whether to check only default branch | false |
true |
PR_BRANCH_PREFIX | PullRequest branch prefix | toc-generator/ |
|
PR_BRANCH_NAME | PullRequest branch name Context variables |
update-toc-${PR_ID} |
toc-${PR_NUMBER} |
PR_TITLE | PullRequest title Context variables |
chore(docs): update TOC (${PR_MERGE_REF}) |
docs: update TOC |
PR_BODY | PullRequest body Context PR variables |
action.yml | |
PR_COMMENT_BODY | PullRequest body for comment Context PR variables |
action.yml | |
PR_CLOSE_MESSAGE | Message body when closing PullRequest | This PR has been closed because it is no longer needed. |
|
TARGET_BRANCH_PREFIX | Filter by branch name | release/ |
|
INCLUDE_LABELS | Labels used to check if the PullRequest has it | Label1, Label2 |
|
OPENING_COMMENT | Opening comment (for other than DocToc) | <!-- toc |
|
CLOSING_COMMENT | Closing comment (for other than DocToc) | <!-- tocstop |
|
SKIP_COMMENT | Change skip comment (default: <!-- DOCTOC SKIP ) |
<!-- toc skip |
|
GITHUB_TOKEN | Access token | ${{github.token}} |
${{secrets.ACCESS_TOKEN}} |
SIGNOFF | Add Signed-off-by line |
true |
Specify options individually
The options used for doctoc can be commented to specify values.
If you want to generate multiple TOCs with different settings, specify the values individually as follows.
e.g.
<!-- START doctoc -->
<!-- param::isNotitle::true:: -->
<!-- param::isCustomMode::true:: -->
<!-- END doctoc -->
...
Action event details
Target event
eventName: action | condition |
---|---|
push: * | condition1 |
pull_request: [opened, synchronize, reopened, labeled, unlabeled] | condition2 |
pull_request: [closed] | |
schedule, repository_dispatch, workflow_dispatch |
- The following activity types must be explicitly specified (detail)
labeled
,unlabeled
,closed
Conditions
condition1
- push to branch (not tag)
- branch name (
TARGET_BRANCH_PREFIX
)
- branch name (
condition2
- specified labels included? (
INCLUDE_LABELS
) - branch name (
TARGET_BRANCH_PREFIX
)
Addition
GITHUB_TOKEN
The GITHUB_TOKEN
that is provided as a part of GitHub Actions
doesn't have authorization to create any successive events.
So it won't spawn actions which triggered by push.
This can be a problem if you have branch protection configured.
If you want to trigger actions, use a personal access token instead.
- Generate a personal access token with the public_repo or repo scope.
(repo is required for private repositories). - Save as ACCESS_TOKEN
- Add input to use
ACCESS_TOKEN
instead ofGITHUB_TOKEN
.
e.g..github/workflows/toc.yml
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 }}
Create PullRequest
If CREATE_PR
is set to true
, a PullRequest is created.
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
If the closed
activity type is set, this action closes the PR when it is no longer needed.
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
Context variables
name | description |
---|---|
PR_NUMBER | pull_request.number (e.g. 11 ) |
PR_NUMBER_REF | #${pull_request.number} (e.g. #11 ) |
PR_ID | pull_request.id (e.g. 21031067 ) |
PR_HEAD_REF | pull_request.head.ref (e.g. change ) |
PR_BASE_REF | pull_request.base.ref (e.g. main ) |
PR_MERGE_REF | pull_request.base.ref (e.g. change -> main ) |
PR_TITLE | pull_request.title (e.g. update the README with new information. ) |
Context PR variables
name | description |
---|---|
PR_LINK | Link to PR |
COMMANDS_OUTPUT | Result of TOC command |
FILES_SUMMARY | e.g. Changed 2 files |
FILES | Changed file list |
Configuration Examples
Example 1
Execute actions at push without limiting the branch and commit directly
on: push
name: TOC Generator
jobs:
generateTOC:
name: TOC Generator
runs-on: ubuntu-latest
steps:
- uses: technote-space/toc-generator@v4
Example 2
Create or update a Pull Request by executing actions on a Pull Request update only for branches starting with release/
.
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/
Example 3
Execute actions in the schedule for the default branch only and commit directly.
(Using the Token created for the launch of other workflows)
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