3
Watch
163
Star
25
Fork
58
Issue

GitHub Actions to generate TOC (Table of Contents)

technote-space
technote-space
pushedAt 2 days ago

technote-space/toc-generator

TOC Generator

CI Status codecov CodeFactor License: MIT

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

  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/[email protected]

Screenshot

behavior

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

condition2

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/[email protected]
            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/[email protected]
        with:
          CREATE_PR: true

create pr

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/[email protected]

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

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/[email protected]

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/[email protected]
        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/[email protected]
        with:
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          CHECK_ONLY_DEFAULT_BRANCH: true

Author

GitHub (Technote)
Blog

ucloud ads