bitflight-devops
![branding<icon:book-open color:yellow>]()
GitHub Action: GitHub Action's Readme Generator
📓 The docs generator for GitHub Actions. Auto-syncs action.yml → README.md with 8 sections including inputs, outputs, usage, badges & branding. Sensible defaults, highly configurable.
Quick Start
npx github-action-readme-generatorThat's it. Run this in your GitHub Action repository and your README.md is updated.
Features
| | Feature | Description |
| :----------------: | ------------------- | ------------------------------------------------------------ |
| :white_check_mark: | Inputs Table | Auto-generates markdown table from action.yml inputs |
| :white_check_mark: | Outputs Table | Auto-generates markdown table from action.yml outputs |
| :white_check_mark: | Usage Example | Creates ready-to-copy YAML workflow snippet |
| :white_check_mark: | Auto-Versioning | Updates uses: owner/repo@v1.2.3 on every release |
| :white_check_mark: | GitHub Badges | Adds release, commit, issues, and download badges |
| :white_check_mark: | SVG Branding | Generates icon from action.yml branding (100+ icons) |
| :white_check_mark: | Easy Setup | Add section markers to README, configure via .ghadocs.json |
| :white_check_mark: | Dual Mode | Use as CLI (npx) or GitHub Action in workflows |
How It Works
This tool uses markdown comments as section markers in your README:
<!-- start inputs -->
<!-- end inputs -->Run the generator, and content between these markers is automatically updated from your action.yml. See README.example.md for a complete template.
Works as both CLI and GitHub Action - configure via .ghadocs.json, command line args, or the Action's with: section.
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
npx --yes github-action-readme-generator@latestInstall with Yarn or NPM as a dev dependency
yarn add -D github-action-readme-generator
# or
npm i --save-dev github-action-readme-generatorAdd 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"
}
}Using as a Pre-commit Hook
You can automate README generation on every commit by using this tool as a pre-commit hook. This ensures your documentation stays up-to-date automatically.
- Install the tool locally (if you haven't already):
npm install --save-dev github-action-readme-generator
# or
yarn add -D github-action-readme-generator- Configure pre-commit:
Add the following to your .pre-commit-config.yaml file:
repos:
- repo: local
hooks:
- id: github-action-readme-generator
name: Generate README from action.yml
entry: npx github-action-readme-generator
language: system
files: ^(action\.yml|\.ghadocs\.json)$
pass_filenames: falseThis configuration will automatically regenerate your README whenever action.yml or .ghadocs.json changes.
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
}Table of Contents
Usage
- uses: bitflight-devops/github-action-readme-generator@v1.9.0
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:
|
