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.

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

Screenshot

Options

name	description	default	required	e.g.
TARGET_PATHS	Target file path. (Comma separated, Detail)	`README*.md`	true	`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(Generated Example)	`false`		`true`
COMMIT_MESSAGE	Commit message	`chore(docs): update TOC`	true	`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 check only default branch	`false`		`true`
CHECK_ONLY_DEFAULT_BRANCH	Whether to create PullRequest	`false`		`true`
PR_BRANCH_PREFIX	PullRequest branch prefix	`toc-generator/`	true
PR_BRANCH_NAME	PullRequest branch name Context variables	`update-toc-${PR_ID}`	true	`toc-${PR_NUMBER}`
PR_TITLE	PullRequest title Context variables	`chore(docs): update TOC (${PR_MERGE_REF})`	true	`docs: update TOC`
PR_BODY	PullRequest body Context PR variables	action.yml	true
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`
GITHUB_TOKEN	Access token	`${{github.token}}`	true	`${{secrets.ACCESS_TOKEN}}`

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

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. `master`)
PR_MERGE_REF	pull_request.base.ref (e.g. `change -> master`)
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@v3

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@v3
        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@v3
        with:
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          CHECK_ONLY_DEFAULT_BRANCH: true

Author

GitHub (Technote)
Blog

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!