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 ```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 ``` 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 } ``` ## 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) ## 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: `` 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** | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------ | | 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 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 | 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 main
Output if your action repo is reviewdog/action-eslint:
uses: reviewdog/action-eslint@main | main | **false** | | version_source | 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 | git-tag | **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.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} | .github/ghadocs/branding.svg | **false** | | branding_as_title_prefix | Prefix the title in the \ section with the svg branding image
The title template looks like this:
# {brand}{prefix}{title} | true | **false** | | **Output** | **Description** | **Value** | | --------------------------------- | -------------------------------------------------------------------- | --------- | | 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 | | **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. ---

**Built by [Bitflight DevOps](https://github.com/bitflight-devops)**