Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zheng-bote/gha-doctoc
Github Action generates table of contents for markdown files.
https://github.com/zheng-bote/gha-doctoc
github-actions markdown
Last synced: 2 days ago
JSON representation
Github Action generates table of contents for markdown files.
- Host: GitHub
- URL: https://github.com/zheng-bote/gha-doctoc
- Owner: Zheng-Bote
- License: mit
- Created: 2024-09-11T15:22:32.000Z (16 days ago)
- Default Branch: main
- Last Pushed: 2024-09-11T16:58:29.000Z (16 days ago)
- Last Synced: 2024-09-26T03:06:42.103Z (2 days ago)
- Topics: github-actions, markdown
- Homepage:
- Size: 338 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
GH Action doctoc
GH Action to create Table of Contents in Markdonw files
[Report Issue](https://github.com/Zheng-Bote/gha-doctoc/issues) [Request Feature](https://github.com/Zheng-Bote/gha-doctoc/pulls)
[](https://choosealicense.com/licenses/mit/)
**Table of Contents**
- [Description](#description)
- [Features](#features)
- [Status](#status)
- [Installation](#installation)
- [Dependencies](#dependencies)
- [folder structure](#folder-structure)
- [Usage/Examples](#usageexamples)
- [API Reference](#api-reference)
- [Parameters](#parameters)
- [Inputs](#inputs)
- [Outputs](#outputs)
- [Documentation](#documentation)
- [Github Page](#github-page)
- [Screenshots](#screenshots)
- [Authors and License](#authors-and-license)
- [License](#license)
- [Authors](#authors)
- [Code Contributors](#code-contributors)
# Description
Github Action generates table of contents for markdown files inside local git repository.
> \[!NOTE]
> Based on Node.js application [DocToc](https://github.com/thlorenz/doctoc) created by [Thorsten Lorenz](https://github.com/thlorenz) and 
## Features
- \[x] works as designed
- \[ ] no bugs
# Status
[](https://github.com/Zheng-Bote/gha-doctoc/actions/workflows/repo-create_tree_readme.yml)
[](https://github.com/Zheng-Bote/gha-doctoc/actions/workflows/repo-actions_docu.yml)
[](https://github.com/Zheng-Bote/gha-doctoc/actions/workflows/repo-create_doctoc.yml)
# Installation
just use it ;-)
> [!Note]
> not yet tested with GHES
## Dependencies
[DocToc](https://github.com/thlorenz/doctoc)
# folder structure
```
.
├── .github
│ └── workflows
│ ├── repo-actions_docu.yml
│ ├── repo-create_doctoc.yml
│ └── repo-create_tree_readme.yml
├── LICENSE
├── README.md
├── action.yml
├── dist
│ ├── index.js
│ ├── index.js.map
│ ├── licenses.txt
│ └── sourcemap-register.js
└── tree.bak
3 directories, 11 files
```
# Usage/Examples
see `.github/workflows/repo-create_doctoc.yml`:
```yaml
name: Repo - create TOC of README
# description: https://github.com/thlorenz/doctoc
# README.md:
#
#
run-name: create README table of contents by ${{ github.actor }}
on:
workflow_dispatch:
push:
branches:
- "main"
paths:
- "README.md"
permissions:
contents: write
jobs:
generateTOC:
name: TOC Generator
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
ref: "main"
- uses: Zheng-Bote/gha-doctoc@main
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TARGET_PATHS: ./README.md
FOLDING: false
- name: Verify Changed files
uses: tj-actions/verify-changed-files@v20
id: verify_changed_files
with:
files: |
README.md
- name: README.md changed
if: steps.verify_changed_files.outputs.files_changed == 'false'
run: |
echo "README.md has no uncommitted changes"
exit 1
- name: commit and push
if: steps.verify_changed_files.outputs.files_changed == 'true'
uses: github-actions-x/[email protected]
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
push-branch: "main"
commit-message: "appended by Github Actions"
force-add: "true"
files: README.md
name: "github-actions[bot]"
email: "github-actions[bot]@users.noreply.github.com"
```
# API Reference
## Parameters
> \[!IMPORTANT]
> Inputs support still in progress.
## Inputs
| INPUT | TYPE | REQUIRED | DEFAULT | DESCRIPTION |
|-------------------------------------------------------------------------------------------------------------|--------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| [API_TOKEN](#input_API_TOKEN) | string | false | | Secret GitHub API token used
to make API requests. |
| [CHECK_ONLY_DEFAULT_BRANCH](#input_CHECK_ONLY_DEFAULT_BRANCH) | string | false | | Whether to check only default
branch. |
| [CLOSING_COMMENT](#input_CLOSING_COMMENT) | string | false | `"
## Outputs
No outputs.
# Documentation
```mermaid
graph TD;
Workflow-. parameter .->Callable_Workflow;
Callable_Workflow-- parameter -->Action;
```
## Github Page
[](https://www.github.com/Zheng-Bote)
see also:
> \[!NOTE]
> Useful information that users should know, even when skimming content.
> \[!TIP]
> Helpful advice for doing things better or more easily.
> \[!IMPORTANT]
> Key information users need to know to achieve their goal.
> \[!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
> \[!CAUTION]
> Advises about risks or negative outcomes of certain actions.
## Screenshots
# Authors and License
## License
**MIT License**
- doctoc (see `dist` folder): Copyright 2013 Thorsten Lorenz.
- gha-doctoc (GH Action and Workflows): Copyright (c) 2024 ZHENG Robert
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
https://choosealicense.com/licenses/mit/
## Authors
- [](https://www.github.com/thlorenz)
- [](https://www.github.com/Zheng-Bote)
## Code Contributors
[](https://www.github.com/Zheng-Bote)
:vulcan_salute: