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.

Details

Installation
Screenshot
Options
- Specify options individually
Action event details
- Target event
- Conditions
Addition
Configuration Examples
Author

Installation

Specify location of TOC (option)
e.g. README.md
```


```
detail

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)

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 of GITHUB_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.`)

Payload example

Context PR variables

Context 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

Author

GitHub (Technote)
Blog

technote-space / toc-generator