github-action-readme-generator v1.8.0
GitHub Action: GitHub Action's Readme Generator
š Keep your action's README.md up to date with the title
and description
from the 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
file. Configuration can be provided through a .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 <!-- start section --><!-- stop section -->
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
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 numberboolean | 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
npx --yes github-action-readme-generator@latest
Install with Yarn or NPM as a dev dependency
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.
{
"scripts": {
"ghadocs": "github-action-readme-generator --readme README.md && git add README.md"
}
}
Configuration
Example .ghadocs.json
with all possible values
{
"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
- 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: `<!-- start branding --><!-- stop branding -->` 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 `<!-- start title -->` 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 |
---|---|---|---|
action | The absolute or relative path to the action.yml file to read in from. | action.yml | false |
readme | The absolute or relative path to the markdown output file that contains the formatting tokens within it. | README.md | false |
owner | The GitHub Action repository owner, this field is autodetected by default.Example: bitflight-devops or your-gh-username | false | |
repo | The GitHub Action repository name, this field is autodetected by default.Example: github-action-readme-generator | false | |
save | Save the provided values in a .ghadocs.json file.This will update any existing .ghadocs.json file that is in place. | false | |
pretty | Use prettier to pretty print the new README.md file | true | false |
versioning_enabled | Enable the update of the usage version to match the latest version in the package.json fileOutput if your action repo is reviewdog/action-eslint and version in package.json is 1.0.1:uses: reviewdog/action-eslint@1.0.1 | true | false |
version_override | Set a specific version to display in the README.md, maybe you want to use a major or minor version | false | |
version_prefix | Prefix the version with this value, if it isn't already prefixed | v | false |
versioning_default_branch | If versioning is disabled, use this branch in the usage example, where the default is mainOutput if your action repo is reviewdog/action-eslint:uses: reviewdog/action-eslint@main | main | false |
title_prefix | Add a prefix to the README title.The title template looks like this:# {brand}{prefix}{title} | GitHub Action: | false |
include_github_version_badge | Include additional badge showing latest tag | true | false |
branding_svg_path | Create the branding svg image from the branding object in action.ymlthen 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: trueto prefix the 'title' section with the image.The title template looks like this:# {brand}{prefix}{title} | .github/ghadocs/branding.svg | false |
branding_as_title_prefix | Prefix the title in the \ section with the svg branding imageThe title template looks like this:# {brand}{prefix}{title} | true | false |
Output | Description |
---|---|
sections | A json object containing a map of section names to their new content |
readme | The path to the generated README.md file |
readme_before | The content of the readme file before the changes were made |
readme_after | The content of the readme file after the changes were made |
7 months ago
6 months ago
7 months ago
7 months ago
7 months ago
7 months ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago