github-action-readme-generator

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/github-action-readme-generator@v1.7.2
  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 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
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: <!-- 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}	.github/ghadocs/branding.svg	false
branding_as_title_prefix	Prefix the title in the <!-- start title --> section with the svg branding image The 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