bohdanm-avispl / toc-generator

GitHub Actions to generate TOC (Table of Contents)

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
• Screenshot
• Options
  • Specify options individually
• Action event details
  • Target event
  • Conditions
• Addition
  • GITHUB_TOKEN
  • Create PullRequest
  • Context variables
  • Context PR variables
• Configuration Examples
  • Example 1
  • Example 2
  • Example 3
• 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@v4

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	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 create PullRequest	false		true
CHECK_ONLY_DEFAULT_BRANCH	Whether to check only default branch	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}}

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.

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