github-action-readme-generator

KO | EN

gitlite — search

#python #javascript #typescript #docker #mysql #css #nodejs #php #react #machine-learning #java #html

github-action-readme-generator

★ 28 Open GitHub ↗

📓 The docs generator for GitHub Actions. Auto-generates inputs, outputs, usage & badges from action.yml.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

</div>

# <img src=".github/ghadocs/branding.svg" width="60px" align="center" alt="branding<icon:book-open color:yellow>" /> GitHub Action: GitHub Action's Readme Generator

</div>

📓 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.12.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: 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** |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------ |
| <code>action</code> | The absolute or relative path to the <code>action.yml</code> file to read in from. | <code>action.yml</code> | **false** |
| <code>readme</code> | The absolute or relative path to the markdown output file that contains the formatting tokens within it. | <code>README.md</code> | **false** |
| <code>owner</code> | The GitHub Action repository owner, this field is autodetected by default. Example: <code>bitflight-devops</code> or <code>your-gh-username</code> | | **false** |
| <code>repo</code> | The GitHub Action repository name, this field is autodetected by default. Example: <code>github-action-readme-generator</code> | | **false** |
| <code>save</code> | Save the provided values in a <code>.ghadocs.json</code> file. This will update any existing <code>.ghadocs.json</code> file that is in place. | | **false** |
| <code>pretty</code> | Use <code>prettier</code> to pretty print the new README.md file | <code>true</code> | **false** |
| <code>versioning_enabled</code> | Enable the update of the usage version to match the latest version in the <code>package.json</code> file Output if your action repo is <code>reviewdog/action-eslint</code> and version in package.json is <code>1.0.1</code>: <code>uses: reviewdog/action-eslint@1.0.1</code> | <code>true</code> | **false** |
| <code>version_override</code> | Set a specific version to display in the README.md, maybe you want to use a major or minor version | | **false** |
| <code>version_prefix</code> | Prefix the version with this value, if it isn't already prefixed | <code>v</code> | **false** |
| <code>versioning_default_branch</code> | If versioning is disabled, use this branch in the usage example, where the default is <code>main</code> Output if your action repo is <code>reviewdog/action-eslint</code>: <code>uses: reviewdog/action-eslint@main</code> | <code>main</code> | **false** |
| <code>version_source</code> | How to detect the action version for the usage example. Options: - <code>git-tag</code> - Latest git tag (default, standard for GitHub Actions) - <code>git-branch</code> - Current branch name (for bleeding edge users) - <code>git-sha</code> - Current commit SHA (for exact pinning) - <code>package-json</code> - Read from package.json version field - <code>explicit</code> - Use value from <code>version_override</code> input only | <code>git-tag</code> | **false** |
| <code>title_prefix</code> | Add a prefix to the README title. The title template looks like this: # {brand}{prefix}{title} | <code>GitHub Action: </code> | **false** |
| <code>include_github_version_badge</code> | Include additional badge showing latest tag | <code>true</code> | **false** |
| <code>branding_svg_path</code> | Create the branding svg image from the branding object in <code>action.yml</code> then save it to this path. Then update the <code>README.md</code> file to source the branding image from this path. You can use a section template like this: <code>\\</code> or use the action input: <code>branding_as_title_prefix: true</code> to prefix the 'title' section with the image. The title template looks like this: # {brand}{prefix}{title} | <code>.github/ghadocs/branding.svg</code> | **false** |
| <code>branding_as_title_prefix</code> | Prefix the title in the <code>\</code> section with the svg branding image The title template looks like this: # {brand}{prefix}{title} | <code>true</code> | **false** |

| **Output** | **Description** | **Value** |
| --------------------------------- | -------------------------------------------------------------------- | --------- |
| <code>sections</code> | A json object containing a map of section names to their new content | |
| <code>readme</code> | The path to the generated README.md file | |
| <code>readme_before</code> | The content of the readme file before the changes were made | |
| <code>readme_after</code> | 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)**

</div>

github-action-readme-generator

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README