自动为README添加TOC目录
GitHub的Markdown目前不支持直接[TOC]渲染文章的目录，有些README则需要这样的效果，可以借助外部工具进行生成，也可以借助 GitHub Actions 自动生成，本文就介绍这种方式。
所用Actions：TOC Generator (opens new window)
使用配置其实非常简单，基本上阅读完官方介绍文档就可以上手使用了，这里说一两个需要注意的地方。
首先需要在将要生成目录的文件内，指定目录生成位置，e.g. README.md，在要生成的地方添加如下内容：
<!-- START doctoc -->
<!-- END doctoc -->
1
2
2
然后添加Actions配置文件，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
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
接着需要调整下项目的Actions权限，在GitHub上点击settings--> actions --> General --> Workflow permissions --> 选择 Read and write permissions。
配置调整完成之后，就可以push项目看效果了，当然这里也可以通过GitHub_Token的方式认证，就不赘述了。
效果呈现如下：
配置列表：
| 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 | 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 create PullRequest | false | true | |
| CHECK_ONLY_DEFAULT_BRANCH | Whether to check only default branch | 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}} |
可根据自己的实际需求以及情况进行配置！
# 另外
后来在一个地方学到了一招，原来GitHub针对Markdown文件已经默认支持了目录的方式，并且还支持搜索，如下：
