Read this in other languages: English, 日本語.
This is a GitHub Actions to generate TOC (Table of Contents),
which executes DocToc and commits if changed.
Details
- Specify location of TOC (option)
e.g.README.mddetail<!-- START doctoc --> <!-- END doctoc -->
- Setup workflow
e.g..github/workflows/toc.ymlon: push name: TOC Generator jobs: generateTOC: name: TOC Generator runs-on: ubuntu-latest steps: - uses: technote-space/toc-generator@v4
| 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 |
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 -->
...
| 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
- push to branch (not tag)
- branch name (
TARGET_BRANCH_PREFIX)
- branch name (
- specified labels included? (
INCLUDE_LABELS) - branch name (
TARGET_BRANCH_PREFIX)
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_TOKENinstead ofGITHUB_TOKEN.
e.g..github/workflows/toc.ymlon: 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 }}
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| 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.) |
| name | description |
|---|---|
| PR_LINK | Link to PR |
| COMMANDS_OUTPUT | Result of TOC command |
| FILES_SUMMARY | e.g. Changed 2 files |
| FILES | Changed file list |
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@v4Create 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/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![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent