hanxiao / toc-generator

GitHub Actions to generate TOC (Table of Contents)

TOC Generator

Read this in other languages: English, 日本語.

This is a GitHub Action to generate TOC (Table of Contents),
which executes DocToc and commits if changed.

Table of Contents

Details

• Installation
• Screenshot
• Options
• Action event details
  • Target event
  • Conditions
• Addition
  • GITHUB_TOKEN
  • Create PullRequest
  • Context variables
  • Context PR variables
• Sample repositories using this Action
• 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@v2

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
FOLDING	Whether to make TOC foldable	false		true
COMMIT_MESSAGE	Commit message	docs: update TOC	true	feat: update TOC
COMMIT_NAME	Git commit name	${github.actor}
COMMIT_EMAIL	Git commit email	${github.actor}@users.noreply.github.com
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	docs: update TOC (${PR_MERGE_REF})	true	feat: 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]

• 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?
• 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@v2
           with:
             GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}

Create PullRequest

If you set pull_request event like following yaml, changes will be committed to PullRequest.

on: pull_request
name: TOC Generator
jobs:
 generateTOC:
   name: TOC Generator
   runs-on: ubuntu-latest
   steps:
     - uses: technote-space/toc-generator@v2

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

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

Sample repositories using this Action

• Release GitHub Actions
  • toc.yml
• Auto card labeler
  • toc.yml
• Assign Author
  • toc.yml
• TOC Generator
  • toc.yml
• Package Version Check Action
  • toc.yml

Author

GitHub (Technote)
Blog