GitHub Action: GitHub Action's Readme Generator

📓 Keep your action's README.md up to date with the title and description from the action.yml file, while also automatically generating sections for the inputs, outputs, and a usage example for the action. Additionally the Action's usage example is updated to match the Action's current release. This is both a CLI tool and GitHub Action that will read the details from a GitHub Action's action.yml file. 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. HOW 📝 This tool uses markdown comments like this <!-- start section --><!-- stop section --> as delimiting tokens within your README.md file to determine where to place the generated content. You can find an example README template with all fields filled-in in the README.example.md file.***

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@latest

Install with Yarn or NPM as a dev dependency

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.

{
  "scripts": {
    "ghadocs": "github-action-readme-generator --readme README.md && git add README.md"
  }
}

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
}

Usage

- uses: bitflight-devops/[email protected]
  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/[email protected]`
    #
    # 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/[email protected] | 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:<!-- start branding --><!-- stop branding -->or use the action input:branding_as_title_prefix: trueto 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 <!-- start title --> section with the svg branding imageThe title template looks like this:# {brand}{prefix}{title} | true | false |

| Output | Description | | -------------------------- | -------------------------------------------------------------------- | | 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 |