github-action-readme-generator
Version:
The docs generator for GitHub Actions. Auto-syncs action.yml to README.md with 8 sections: inputs, outputs, usage, badges, branding & more. Works as CLI or GitHub Action.
335 lines (259 loc) ā¢ 23.6 kB
Markdown
<div align="center">
<img src=".github/hero.png" alt="GitHub Action README Generator" width="800" />
</div>
<div align="center" >
<!-- start title -->
# <img src=".github/ghadocs/branding.svg" width="60px" align="center" alt="branding<icon:book-open color:yellow>" /> GitHub Action: GitHub Action's Readme Generator
<!-- end title -->
<!-- start badges -->
<a href="https%3A%2F%2Fgithub.com%2Fbitflight-devops%2Fgithub-action-readme-generator%2Freleases%2Flatest"><img src="https://img.shields.io/github/v/release/bitflight-devops/github-action-readme-generator?display_name=tag&sort=semver&logo=github&style=flat-square" alt="Release%20by%20tag" /></a><a href="https%3A%2F%2Fgithub.com%2Fbitflight-devops%2Fgithub-action-readme-generator%2Freleases%2Flatest"><img src="https://img.shields.io/github/release-date/bitflight-devops/github-action-readme-generator?display_name=tag&sort=semver&logo=github&style=flat-square" alt="Release%20by%20date" /></a><img src="https://img.shields.io/github/last-commit/bitflight-devops/github-action-readme-generator?logo=github&style=flat-square" alt="Commit" /><a href="https%3A%2F%2Fgithub.com%2Fbitflight-devops%2Fgithub-action-readme-generator%2Fissues"><img src="https://img.shields.io/github/issues/bitflight-devops/github-action-readme-generator?logo=github&style=flat-square" alt="Open%20Issues" /></a><img src="https://img.shields.io/github/downloads/bitflight-devops/github-action-readme-generator/total?logo=github&style=flat-square" alt="Downloads" />
<!-- end badges -->
<br />
</div>
<!-- start description -->
š 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.
<!-- end description -->
## Quick Start
```sh
npx github-action-readme-generator
```
That'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:
```markdown
<!-- start inputs -->
<!-- end inputs -->
```
Run the generator, and content between these markers is automatically updated from your `action.yml`. See [`README.example.md`](./README.example.md) for a complete template.
**Works as both CLI and GitHub Action** - configure via [`.ghadocs.json`](./.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
```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"
}
}
```
### 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.
1. **Install the tool locally** (if you haven't already):
```sh
npm install --save-dev github-action-readme-generator
# or
yarn add -D github-action-readme-generator
```
2. **Configure pre-commit**:
Add the following to your `.pre-commit-config.yaml` file:
```yaml
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: false
```
This configuration will automatically regenerate your README whenever `action.yml` or `.ghadocs.json` changes.
## 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
}
```
<!-- start contents -->
## Table of Contents
- [Quick Start](#quick-start)
- [Features](#features)
- [How It Works](#how-it-works)
- [CLI Usage](#cli-usage)
- [Stand Alone Usage - if you have a Docker Action](#stand-alone-usage-if-you-have-a-docker-action)
- [Install with Yarn or NPM as a dev dependency](#install-with-yarn-or-npm-as-a-dev-dependency)
- [Add a script to your project file](#add-a-script-to-your-project-file)
- [Using as a Pre-commit Hook](#using-as-a-pre-commit-hook)
- [Configuration](#configuration)
- [Example `.ghadocs.json` with all possible values](#example-ghadocsjson-with-all-possible-values)
- [Usage](#usage)
- [Inputs](#inputs)
<!-- end contents -->
## Usage
<!-- start usage -->
```yaml
- uses: bitflight-devops/github-action-readme-generator@v1
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: How to detect the action version for the usage example. Options:
#
# - `git-tag` - Latest git tag (default, standard for GitHub Actions)
# - `git-branch` - Current branch name (for bleeding edge users)
# - `git-sha` - Current commit SHA (for exact pinning)
# - `package-json` - Read from package.json version field
# - `explicit` - Use value from `version_override` input only
#
# Default: git-tag
version_source: ""
# 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: ""
```
<!-- end usage -->
## Inputs
<!-- start inputs -->
| **Input** | **Description** | **Default** | **Required** |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------ |
| <b><code>action</code></b> | The absolute or relative path to the <code>action.yml</code> file to read in from. | <code>action.yml</code> | **false** |
| <b><code>readme</code></b> | The absolute or relative path to the markdown output file that contains the formatting tokens within it. | <code>README.md</code> | **false** |
| <b><code>owner</code></b> | The GitHub Action repository owner, this field is autodetected by default.<br />Example: <code>bitflight-devops</code> or <code>your-gh-username</code> | | **false** |
| <b><code>repo</code></b> | The GitHub Action repository name, this field is autodetected by default.<br />Example: <code>github-action-readme-generator</code> | | **false** |
| <b><code>save</code></b> | Save the provided values in a <code>.ghadocs.json</code> file.<br />This will update any existing <code>.ghadocs.json</code> file that is in place. | | **false** |
| <b><code>pretty</code></b> | Use <code>prettier</code> to pretty print the new README.md file | <code>true</code> | **false** |
| <b><code>versioning_enabled</code></b> | Enable the update of the usage version to match the latest version in the <code>package.json</code> file<br />Output if your action repo is <code>reviewdog/action-eslint</code> and version in package.json is <code>1.0.1</code>:<br /><code>uses: reviewdog/action-eslint@1.0.1</code> | <code>true</code> | **false** |
| <b><code>version_override</code></b> | Set a specific version to display in the README.md, maybe you want to use a major or minor version | | **false** |
| <b><code>version_prefix</code></b> | Prefix the version with this value, if it isn't already prefixed | <code>v</code> | **false** |
| <b><code>versioning_default_branch</code></b> | If versioning is disabled, use this branch in the usage example, where the default is <code>main</code><br />Output if your action repo is <code>reviewdog/action-eslint</code>:<br /><code>uses: reviewdog/action-eslint@main</code> | <code>main</code> | **false** |
| <b><code>version_source</code></b> | How to detect the action version for the usage example.<br />Options:<br />- <code>git-tag</code> - Latest git tag (default, standard for GitHub Actions)<br />- <code>git-branch</code> - Current branch name (for bleeding edge users)<br />- <code>git-sha</code> - Current commit SHA (for exact pinning)<br />- <code>package-json</code> - Read from package.json version field<br />- <code>explicit</code> - Use value from <code>version_override</code> input only | <code>git-tag</code> | **false** |
| <b><code>title_prefix</code></b> | Add a prefix to the README title.<br />The title template looks like this:<br /># {brand}{prefix}{title} | <code>GitHub Action: </code> | **false** |
| <b><code>include_github_version_badge</code></b> | Include additional badge showing latest tag | <code>true</code> | **false** |
| <b><code>branding_svg_path</code></b> | Create the branding svg image from the branding object in <code>action.yml</code><br />then save it to this path.<br />Then update the <code>README.md</code> file to source the branding image from this path.<br />You can use a section template like this:<br /><code>\<!-- start branding -->\<!-- stop branding --></code><br />or use the action input:<br /><code>branding_as_title_prefix: true</code><br />to prefix the 'title' section with the image.<br />The title template looks like this:<br /># {brand}{prefix}{title} | <code>.github/ghadocs/branding.svg</code> | **false** |
| <b><code>branding_as_title_prefix</code></b> | Prefix the title in the <code>\<!-- start title --></code> section with the svg branding image<br />The title template looks like this:<br /># {brand}{prefix}{title} | <code>true</code> | **false** |
<!-- end inputs -->
<!-- start outputs -->
| **Output** | **Description** | **Value** |
| --------------------------------- | -------------------------------------------------------------------- | --------- |
| <b><code>sections</code></b> | A json object containing a map of section names to their new content | |
| <b><code>readme</code></b> | The path to the generated README.md file | |
| <b><code>readme_before</code></b> | The content of the readme file before the changes were made | |
| <b><code>readme_after</code></b> | The content of the readme file after the changes were made | |
<!-- end outputs -->
**NOTE**: [volta.sh](https://volta.sh/) is a great tool for managing node versions, and is configured in this directory. If you have volta installed, you can run `volta install` to install the correct version of node for this project.
<!-- start [.github/ghadocs/examples/] -->
<!-- end [.github/ghadocs/examples/] -->
---
<div align="center">
<img src=".github/bitflight-devops.png" alt="Bitflight DevOps" width="400" />
**Built by [Bitflight DevOps](https://github.com/bitflight-devops)**
</div>