toc-generator

GitHub Actions to generate TOC (Table of Contents)

View project on GitHub

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.

Installation | Screenshot | Options | Action event details | Addition | Configuration Examples | 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@v3

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|\|\| | | |FOLDING|Whether to make TOC foldable(Generated Example)|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 check only default branch|false| |true| |CHECK_ONLY_DEFAULT_BRANCH|Whether to create PullRequest|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|$|true|$|

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

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@v3
        with:
          GITHUB_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@v3
        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/toc-generator@v3

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

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

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@v3
        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@v3
        with:
          GITHUB_TOKEN: $
          CHECK_ONLY_DEFAULT_BRANCH: true

Author

GitHub (Technote)
Blog