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 | Screenshot | Options | Action event details | Addition | Configuration Examples | Author

Installation

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

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

   detail
2. 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.

1. Generate a personal access token with the public_repo or repo scope.
   (repo is required for private repositories).
2. Save as ACCESS_TOKEN
3. 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