README.md

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

• Screenshot
• Installation
• Options
  • TARGET_PATHS
  • TOC_TITLE
  • MAX_HEADER_LEVEL
  • FOLDING
  • COMMIT_MESSAGE
  • COMMIT_NAME
  • COMMIT_EMAIL
  • PR_BRANCH_PREFIX
  • PR_BRANCH_NAME
  • PR_TITLE
  • PR_BODY
  • PR_COMMENT_BODY
  • PR_CLOSE_MESSAGE
  • TARGET_BRANCH_PREFIX
  • INCLUDE_LABELS
• Action event details
  • Target event
  • Conditions
• Addition
  • Commit
  • Create PullRequest
  • Context variables
  • Context PR variables
• Sample repositories using this Action
• Author

Screenshot

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:
         - name: TOC Generator
           uses: technote-space/toc-generator@v2
           with:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Options

TARGET_PATHS

Target file path. (Comma separated, Detail)
default: 'README*.md'
e.g. .

TOC_TITLE

TOC Title.
default: '**Table of Contents**'
e.g. ''

MAX_HEADER_LEVEL

Maximum heading level. (Detail)
default: ``
e.g. 3

FOLDING

Whether to make TOC foldable.
default: false
e.g. 'true'

COMMIT_MESSAGE

Commit message.
default: 'docs: update TOC'
e.g. feat: update TOC

COMMIT_NAME

Git commit name.
default: '${github.actor}'
About Github Context

COMMIT_EMAIL

Git commit email.
default: '${github.actor}@users.noreply.github.com'
About Github Context

PR_BRANCH_PREFIX

PullRequest branch prefix.
default: 'toc-generator/'

PR_BRANCH_NAME

PullRequest branch name.
default: 'update-toc-${PR_ID}'
e.g. toc-${PR_NUMBER}
Context variables

PR_TITLE

PullRequest title.
default: 'docs: Update TOC (${PR_MERGE_REF})'
e.g. feat: update TOC
Context variables

PR_BODY

PullRequest body.
default:

## Base PullRequest

${PR_TITLE} (${PR_NUMBER_REF})

## Command results
<details>
  <summary>Details: </summary>

  ${COMMANDS_OUTPUT}

</details>

## Changed files
<details>
  <summary>${FILES_SUMMARY}: </summary>

  ${FILES}

</details>

<hr>

[:octocat: Repo](${ACTION_URL}) | [:memo: Issues](${ACTION_URL}/issues) | [:department_store: Marketplace](${ACTION_MARKETPLACE_URL})

Context PR variables

PR_COMMENT_BODY

PullRequest body for comment.
default:

## Command results
<details>
  <summary>Details: </summary>

  ${COMMANDS_OUTPUT}

</details>

## Changed files
<details>
  <summary>${FILES_SUMMARY}: </summary>

  ${FILES}

</details>

<hr>

[:octocat: Repo](${ACTION_URL}) | [:memo: Issues](${ACTION_URL}/issues) | [:department_store: Marketplace](${ACTION_MARKETPLACE_URL})

Context PR variables

PR_CLOSE_MESSAGE

Message body when closing PullRequest.
default: 'This PR is no longer needed because the package looks up-to-date.'

TARGET_BRANCH_PREFIX

Filter by branch name.
default: ''
e.g. 'release/'

INCLUDE_LABELS

Labels used to check if the PullRequest has it.
default: ''
e.g. 'Label1, Label2'
e.g.

INCLUDE_LABELS: |
  Test Label1
  Test Label2

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

Commit

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. 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:
         - name: TOC Generator
           uses: technote-space/toc-generator@v2
           with:
             # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
             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:
     - name: TOC Generator
       uses: technote-space/toc-generator@v2
       with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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:
     - name: TOC Generator
       uses: technote-space/toc-generator@v2
       with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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