# @technote-space/toc-generator

> GitHub Action to generate TOC.

Latest version **4.3.1** (published 2022-12-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @technote-space/toc-generator
pnpm add @technote-space/toc-generator
yarn add @technote-space/toc-generator
bun add @technote-space/toc-generator
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.3.1 |
| Published | 2022-12-11 |
| First published | 2020-02-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 1.8 MB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 246 |
| Author | Technote |
| Maintainers | technote |
| Keywords | github, github actions, toc |

## Links

- npm: https://www.npmjs.com/package/@technote-space/toc-generator
- Repository: https://github.com/technote-space/toc-generator
- Issues: https://github.com/technote-space/toc-generator/issues
- npm.io page: https://npm.io/package/@technote-space/toc-generator

## Recent versions

- 4.3.1 (latest) — 2022-12-11
- 4.3.0 — 2022-12-11
- 4.2.2 — 2022-11-03
- 4.2.1 — 2022-06-21
- 4.2.0 — 2022-06-21
- 4.1.6 — 2022-01-04
- 4.1.5 — 2021-11-12
- 4.1.4 — 2021-09-05
- 4.1.3 — 2021-06-22
- 4.1.2 — 2021-04-29
- 4.1.1 — 2021-03-19
- 4.1.0 — 2021-03-16
- 4.0.2 — 2021-02-26
- 4.0.1 — 2021-02-26
- 4.0.0 — 2021-02-07
- … 31 more at https://npm.io/package/@technote-space/toc-generator/versions

## README

# TOC Generator

[![CI Status](https://github.com/technote-space/toc-generator/workflows/CI/badge.svg)](https://github.com/technote-space/toc-generator/actions)
[![codecov](https://codecov.io/gh/technote-space/toc-generator/branch/main/graph/badge.svg)](https://codecov.io/gh/technote-space/toc-generator)
[![CodeFactor](https://www.codefactor.io/repository/github/technote-space/toc-generator/badge)](https://www.codefactor.io/repository/github/technote-space/toc-generator)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/technote-space/toc-generator/blob/main/LICENSE)

*Read this in other languages: [English](README.md), [日本語](README.ja.md).*

This is a `GitHub Actions` to generate TOC (Table of Contents),  
which executes [DocToc](https://github.com/thlorenz/doctoc) and commits if changed.

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<details>
<summary>Details</summary>

- [Installation](#installation)
- [Screenshot](#screenshot)
- [Options](#options)
  - [Specify options individually](#specify-options-individually)
- [Action event details](#action-event-details)
  - [Target event](#target-event)
  - [Conditions](#conditions)
- [Addition](#addition)
  - [GITHUB_TOKEN](#github_token)
  - [Create PullRequest](#create-pullrequest)
  - [Context variables](#context-variables)
  - [Context PR variables](#context-pr-variables)
- [Configuration Examples](#configuration-examples)
  - [Example 1](#example-1)
  - [Example 2](#example-2)
  - [Example 3](#example-3)
- [Author](#author)

</details>
<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation
1. Specify location of TOC (option)  
e.g. `README.md`  
   ```markdown
   <!-- START doctoc -->
   <!-- END doctoc -->
   ```
   [detail](https://github.com/thlorenz/doctoc#specifying-location-of-toc)  
1. Setup workflow  
   e.g. `.github/workflows/toc.yml`
   ```yaml
   on: push
   name: TOC Generator
   jobs:
     generateTOC:
       name: TOC Generator
       runs-on: ubuntu-latest
       steps:
         - uses: technote-space/toc-generator@v4
   ```

## Screenshot
![behavior](https://raw.githubusercontent.com/technote-space/toc-generator/images/screenshot.gif)

## Options
| name | description | default | e.g. |
|:---|:---|:---|:---|
|TARGET_PATHS|Target file path. (Comma separated, [Detail](https://github.com/thlorenz/doctoc#adding-toc-to-individual-files))|`README*.md`|`README*.md,CHANGELOG.md`, `.`|
|TOC_TITLE|TOC Title|`**Table of Contents**`|`''`|
|MAX_HEADER_LEVEL|Maximum heading level. ([Detail](https://github.com/thlorenz/doctoc#specifying-a-maximum-heading-level-for-toc-entries))| |`3`|
|CUSTOM_MODE|Whether it is custom mode([Generated Example](samples/README.horizontal.md))|`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|<code>\<span>&#124;\</span></code>| |
|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<br>[Context variables](#context-variables)|`update-toc-${PR_ID}`|`toc-${PR_NUMBER}`|
|PR_TITLE|PullRequest title<br>[Context variables](#context-variables)|`chore(docs): update TOC (${PR_MERGE_REF})`|`docs: update TOC`|
|PR_BODY|PullRequest body<br>[Context PR variables](#context-pr-variables)|[action.yml](action.yml)| |
|PR_COMMENT_BODY|PullRequest body for comment<br>[Context PR variables](#context-pr-variables)|[action.yml](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](https://github.com/technote-space/doctoc#example) can be commented to specify values.  
If you want to generate multiple TOCs with different settings, specify the values individually as follows.

e.g.
```markdown
<!-- START doctoc -->
<!-- param::isNotitle::true:: -->
<!-- param::isCustomMode::true:: -->

<!-- END doctoc -->

...

```

## Action event details
### Target event
| eventName: action | condition |
|:---|:---|
|push: *|[condition1](#condition1)|
|pull_request: \[opened, synchronize, reopened, labeled, unlabeled]|[condition2](#condition2)|
|pull_request: \[closed]||
|schedule, repository_dispatch, workflow_dispatch||

- The following activity types must be explicitly specified ([detail](https://help.github.com/en/github/automating-your-workflow-with-github-actions/events-that-trigger-workflows#pull-request-event-pull_request))
  - `labeled`, `unlabeled`, `closed`
### Conditions
#### condition1
- push to branch (not tag)
  - branch name ([`TARGET_BRANCH_PREFIX`](#options))
#### condition2
- specified labels included? ([`INCLUDE_LABELS`](#options))
- branch name ([`TARGET_BRANCH_PREFIX`](#options))

## 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](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) with the public_repo or repo scope.  
(repo is required for private repositories).  
1. [Save as ACCESS_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)
1. Add input to use `ACCESS_TOKEN` instead of `GITHUB_TOKEN`.  
   e.g. `.github/workflows/toc.yml`
   ```yaml
   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.  

```yaml
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](https://raw.githubusercontent.com/technote-space/toc-generator/images/create_pr.png)

If the `closed` activity type is set, this action closes the PR when it is no longer needed.  

```yaml
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](https://developer.github.com/v3/activity/events/types/#webhook-payload-example-28)

### Context PR variables
- [Context variables](#context-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

```yaml
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/`.

```yaml
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）

```yaml
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)](https://github.com/technote-space)  
[Blog](https://technote.space)

---
_Source: https://npm.io/package/@technote-space/toc-generator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._