• Stars
    star
    219
  • Rank 181,133 (Top 4 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created about 5 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

GitHub Actions to generate TOC (Table of Contents)

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/toc-generator@v4

Screenshot

behavior

Options

name description default e.g.
TARGET_PATHS Target file path. (Comma separated, Detail) README*.md 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 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/
PR_BRANCH_NAME PullRequest branch name
Context variables
update-toc-${PR_ID} toc-${PR_NUMBER}
PR_TITLE PullRequest title
Context variables
chore(docs): update TOC (${PR_MERGE_REF}) docs: update TOC
PR_BODY PullRequest body
Context PR variables
action.yml
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
SKIP_COMMENT Change skip comment (default: <!-- DOCTOC SKIP ) <!-- toc skip
GITHUB_TOKEN Access token ${{github.token}} ${{secrets.ACCESS_TOKEN}}
SIGNOFF Add Signed-off-by line true

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/toc-generator@v4
            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@v4
        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@v4

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/toc-generator@v4

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@v4
        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@v4
        with:
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
          CHECK_ONLY_DEFAULT_BRANCH: true

Author

GitHub (Technote)
Blog

More Repositories

1

get-diff-action

GitHub Actions to get git diff
TypeScript
191
star
2

workflow-conclusion-action

GitHub action to get workflow conclusion.
TypeScript
143
star
3

release-github-actions

GitHub Actions to automate the release of GitHub Actions
TypeScript
80
star
4

assign-author

GitHub Actions to assign author to issue or PR
TypeScript
70
star
5

auto-cancel-redundant-workflow

GitHub Actions to automatically cancel redundant workflow.
TypeScript
59
star
6

package-version-check-action

GitHub Actions to check package version before publish
TypeScript
36
star
7

auto-card-labeler

GitHub actions to auto label a pull request or an issue based on project card move
TypeScript
35
star
8

gh-actions-template

Template for GitHub Actions
TypeScript
31
star
9

create-pr-action

GitHub Actions to manage PullRequest
TypeScript
31
star
10

broken-link-checker-action

GitHub Actions to check broken links and create issues.
TypeScript
24
star
11

add-richtext-toolbar-button

WordPress plugin to add richtext toolbar button
PHP
17
star
12

create-project-card-action

GitHub actions to create project card
TypeScript
15
star
13

pr-commit-body-action

GitHub action to add commit history to PR body
TypeScript
13
star
14

frourio-demo

TypeScript
12
star
15

jquery.marker-animation

Marker animation jQuery plugin
JavaScript
12
star
16

marker-animation

WordPress plugin to add underline animation
PHP
11
star
17

github-action-helper

Helper for GitHub Actions
TypeScript
10
star
18

y-proofreading

WordPress plugin to add feature of Japanese proofreading
PHP
10
star
19

load-config-action

TypeScript
6
star
20

github-action-pr-helper

PullRequest Helper for GitHub Actions
TypeScript
5
star
21

hide-blocks-temporarily

WordPress plugin to hide Gutenberg blocks temporarily
JavaScript
5
star
22

prisma-seeder-tools

TypeScript
4
star
23

ga-framework

Genetic Algorithm Framework
TypeScript
4
star
24

release-github-actions-cli

CLI tool of Release GitHub Actions
TypeScript
4
star
25

register-grouped-format-type

Gutenberg's library to provide method to register grouped RichText format type
JavaScript
4
star
26

laravel-reservation-management-system

Reservation system
PHP
4
star
27

genetic-algorithms-py

Genetic Algorithm
Python
3
star
28

can-npm-publish-action

GitHub Actions to check if it can be published to npm.
TypeScript
3
star
29

github-action-test-helper

Test helper for GitHub Actions.
TypeScript
3
star
30

ga-framework-template

TypeScript
3
star
31

use-local-storage

TypeScript
3
star
32

change-block-keywords

WordPress plugin to change keywords for block search
JavaScript
3
star
33

get-next-version-action

GitHub Actions to get next version from commit histories.
TypeScript
3
star
34

csrf-detector

CSRF Detector for WordPress
PHP
3
star
35

ts-package-template

Template for npm package.
Shell
2
star
36

technote-space

2
star
37

download-annotations-action

GitHub actions to download annotations
TypeScript
2
star
38

github-actions-workflows

Shell
2
star
39

gutenberg-package-versions

Versions of Gutenberg's packages (auto updated by GitHub Actions)
Shell
2
star
40

laravel-search-helper

Search helper for Laravel
PHP
2
star
41

wp-related-post-jp

WordPress recommendation plugin for Japanese
PHP
2
star
42

genetic-algorithms-js

Genetic Algorithms Library
TypeScript
2
star
43

get-git-comment-action

GitHub actions to get git comment.
TypeScript
1
star
44

laravel-crud-helper

CRUD helper for Laravel
PHP
1
star
45

contact-form-7-huge-file-upload

CF7 extension plugin to upload huge file
PHP
1
star
46

worker-controller

Worker Controller
TypeScript
1
star
47

github-action-log-helper

Logging helpers for GitHub Actions
TypeScript
1
star
48

advanced-block-editor

WordPress plugin to add some useful features to block editor
JavaScript
1
star
49

python-setup

Shell
1
star
50

gutenberg-packages

Library to get versions of gutenberg packages
PHP
1
star
51

hello-genetic-algorithm

Generate `Hello,World!` string using Genetic Algorithm
TypeScript
1
star
52

gutenberg-utils

Utility for gutenberg
JavaScript
1
star
53

laravel-transaction-fire-event

PHP
1
star