Skip to content

Latest commit

 

History

History
246 lines (216 loc) · 9.1 KB

README.horizontal.md

File metadata and controls

246 lines (216 loc) · 9.1 KB
Raw

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 <span>|</span>
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 ${{github.token}} true ${{secrets.ACCESS_TOKEN}}

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/toc-generator@v3
        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/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: ${{ secrets.ACCESS_TOKEN }}
          CHECK_ONLY_DEFAULT_BRANCH: true

Author

GitHub (Technote)
Blog