📓 Keep your action's README.md up to date with the `title` and `description` from the [`action.yml`](./action.yml) file, while also automatically generating sections for the inputs, outputs, and a usage example for the action. Additionally the Action's usage example is updated to match the Action's current release.
This is both a CLI tool and GitHub Action that will read the details from a GitHub Action's [`action.yml`](./action.yml) file. Configuration can be provided through a [`.ghadocs.json`](./.ghadocs.json) file stored in the root directory of the Action's repository, via the command line when using the CLI, or through the `with:` section of this Action.
**_HOW_** 📝 This tool uses markdown comments like this `` as delimiting tokens within your README.md file to determine where to place the generated content. You can find an example README template with all fields filled-in in the [`README.example.md`](./README.example.md) file.\*\*\*
## CLI Usage
| Usage Options | Description | Default |
| ---------------------------------- | ------------------------------------------------------------------------------------------- | ---------------- |
| --help | Show help | [boolean] |
| --paths:action, --action | Path to the action.yml | [default: ""] |
| --paths:readme, --readme | Path to the README.md | [default: ""] |
| --show_logo, --logo | Display the action's logo in the README | [default: false] |
| --prettier, --pretty | Format the markdown using prettier formatter | [default: false] |
| --versioning:enabled, --versioning | Enable the update of the usage version to match the latest version in the package.json file | [default: false] |
| --versioning:override, --version | Show version number[boolean] | [default: ""] |
| --versioning:prefix, --vp | Prefix the version with this value (if it isn't already prefixed) | [default: ""] |
| --versioning:branch, --branch | If versioning is disabled show this branch instead | [default: ""] |
| --title_prefix, --prefix | Add a prefix to the README title | [default: ""] |
### Stand Alone Usage - if you have a Docker Action
```sh
npx --yes github-action-readme-generator@latest
```
### Install with Yarn or NPM as a dev dependency
```sh
yarn add -D github-action-readme-generator
# or
npm i --save-dev github-action-readme-generator
```
### Add a script to your project file
You can modify the script below to include any extra variables you like or use none, and instead use a `.ghadocs.json` file.
```json
{
"scripts": {
"ghadocs": "github-action-readme-generator --readme README.md && git add README.md"
}
}
```
## Configuration
### Example `.ghadocs.json` with all possible values
```json
{
"paths": {
"action": "action.yml",
"readme": "README.md"
},
"show_logo": true,
"versioning": {
"enabled": true,
"override": "",
"prefix": "v",
"branch": "main"
},
"owner": "bitflight-devops",
"repo": "github-action-readme-generator",
"title_prefix": "GitHub Action: ",
"prettier": true
}
```
## Usage
```yaml
- uses: bitflight-devops/github-action-readme-generator@v1.7.2
with:
# Description: The absolute or relative path to the `action.yml` file to read in
# from.
#
# Default: action.yml
action: ""
# Description: The absolute or relative path to the markdown output file that
# contains the formatting tokens within it.
#
# Default: README.md
readme: ""
# Description: The GitHub Action repository owner, this field is autodetected by
# default. Example: `bitflight-devops` or `your-gh-username`
#
owner: ""
# Description: The GitHub Action repository name, this field is autodetected by
# default. Example: `github-action-readme-generator`
#
repo: ""
# Description: Save the provided values in a `.ghadocs.json` file. This will
# update any existing `.ghadocs.json` file that is in place.
#
# Default: false
save: ""
# Description: Use `prettier` to pretty print the new README.md file
#
# Default: true
pretty: ""
# Description: Enable the update of the usage version to match the latest version
# in the `package.json` file Output if your action repo is
# `reviewdog/action-eslint` and version in package.json is `1.0.1`:
# `uses: reviewdog/action-eslint@1.0.1`
#
# Default: true
versioning_enabled: ""
# Description: Set a specific version to display in the README.md, maybe you want
# to use a major or minor version
#
version_override: ""
# Description: Prefix the version with this value, if it isn't already prefixed
#
# Default: v
version_prefix: ""
# Description: If versioning is disabled, use this branch in the usage example,
# where the default is `main` Output if your action repo is
# `reviewdog/action-eslint`: `uses: reviewdog/action-eslint@main`
#
# Default: main
versioning_default_branch: ""
# Description: Add a prefix to the README title. The title template looks like
# this:
#
# # {brand}{prefix}{title}
#
# Default: GitHub Action:
title_prefix: ""
# Description: Include additional badge showing latest tag
#
# Default: true
include_github_version_badge: ""
# Description: Create the branding svg image from the branding object in
# `action.yml` then save it to this path. Then update the `README.md` file to
# source the branding image from this path. You can use a section template like
# this: `` or use the action input:
# `branding_as_title_prefix: true` to prefix the 'title' section with the image.
# The title template looks like this:
#
# # {brand}{prefix}{title}
#
# Default: .github/ghadocs/branding.svg
branding_svg_path: ""
# Description: Prefix the title in the `` section with the svg
# branding image The title template looks like this:
#
# # {brand}{prefix}{title}
#
# Default: true
branding_as_title_prefix: ""
```
## Inputs
| **Input** | **Description** | **Default** | **Required** |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------ |
| 
GitHub Action: GitHub Action's Readme Generator
