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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

INCLUDE_LABELS: |
  Test Label1
  Test Label2

• The following activity types must be explicitly specified (detail)
  • labeled, unlabeled, closed

• push to branch (not tag)
  • branch name (TARGET_BRANCH_PREFIX)

• specified labels included?
• branch name (TARGET_BRANCH_PREFIX)

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

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

Payload example

• Context variables

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

GitHub (Technote)
Blog