Maintain a current README.md with content from the action.yml file
This is a CLI tool and GitHub Action that reads the details from a GitHub Action's action.yml
file. It updates the README.md
file with the name
, description
, usage
, inputs
, outputs
, and examples of the action. 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.
π This tool uses markdown comments as delimiting tokens within the README.md file to determine where to place the generated content.
π You can find an example with all fields filled in, and no other free-form content, in the README.example.md
file.
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: ""] |
sh
npx github-action-readme-generator
yarn add -D github-action-readme-generator
# or
npm i --save-dev github-action-readme-generator
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"
}
}
{
"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: ",
"pretty": true
}
- Add section for a title to the generator
- Add section for a description to the generator
- Add word wrapping to multi-line text
- Add section to generate the
action.yml
inputs to a table to the generator - Add section to generate the
action.yml
outputs to a table to the generator - Add a markdown
contents
menu section to the generator - Allow for using a separate template for generating the readme file
- Add section to embed other markdown files or directories by path, so that documentation can be organized in the file system.
i.e.,<!-- start [.github/ghadocs/examples/] -->
and<!-- end [.github/ghadocs/examples/] -->
- uses: bitflight-devops/[email protected]
with:
# The absolute or relative path to the `action.yml` file to read in from.
# Default: action.yml
action: ''
# The absolute or relative path to the markdown output file that contains the
# formatting tokens within it.
# Default: README.md
readme: ''
# The GitHub Action repository owner. i.e: `bitflight-devops`|`your-gh-username`
owner: ''
# The GitHub Action repository name. i.e: `github-action-readme-generator`
repo: ''
# Save the provided values in a `.ghadocs.json` file. This will update any
# existing `.ghadocs.json` file that is in place.
save: ''
# Use `prettier` to pretty print the new README.md file
pretty: ''
# Enable the update of the usage version to match the latest version in the
# `package.json` file
versioning_enabled: ''
# Set a specific version to display in the README.md
version_override: ''
# Prefix the version with this value (if it isn't already prefixed)
# Default: v
version_prefix: ''
# If versioning is disabled show this branch instead
# Default: main
versioning_default_branch: ''
# Add a prefix to the README title
# Default: GitHub Action:
title_prefix: ''
# Include additional badge showing latest tag
# Default: true
include_github_version_badge: ''
**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. i.e: bitflight-devops |your-gh-username |
false | |
repo |
The GitHub Action repository name. i.e: 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 |
false | |
versioning_enabled |
Enable the update of the usage version to match the latest version in the package.json file |
false | |
version_override |
Set a specific version to display in the README.md | false | |
version_prefix |
Prefix the version with this value (if it isn't already prefixed) | v |
false |
versioning_default_branch |
If versioning is disabled show this branch instead | main |
false |
title_prefix |
Add a prefix to the README title | GitHub Action: |
false |
include_github_version_badge |
Include additional badge showing latest tag | true |
false |