Skip to content
GitHub Actions to generate TOC (Table of Contents)
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

TOC Generator

Build Status codecov CodeFactor License: MIT

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

Screenshot

behavior

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@v1
            with:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Options

TARGET_PATHS

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

TOC_TITLE

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

PR_BRANCH_NAME

PullRequest branch name.
If this option is set, changes will be committed to PullRequest.
default: ''
e.g. docs/toc-${PR_NUMBER}
Detail
Context variables

PR_TITLE

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

COMMIT_MESSAGE

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

INCLUDE_LABELS

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

INCLUDE_LABELS: |
  Test Label1
  Test Label2

BRANCH_PREFIX

Branch name prefix.
default: ''
e.g. master

DELETE_PACKAGE

Whether to delete package file before install DocToc for performance.
default: '1'
e.g. ''

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)
  • not set PR_BRANCH_NAME

condition2

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.

GITHUB_TOKEN

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@v1
            with:
              # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}

ACCESS_TOKEN

Create PullRequest

If you set PR_BRANCH_NAME option 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@v1
       with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_BRANCH_NAME: docs/toc-${PR_NUMBER}

create pr

If you want to close PullRequest when PullRequest to merge has been closed, please set closed activity type.

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@v1
       with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_BRANCH_NAME: docs/toc-${PR_NUMBER}

Context variables

name description
PR_NUMBER 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)

Payload example

GitHub Actions using this Action

Author

GitHub (Technote)
Blog

You can’t perform that action at this time.