JSPM – github-action-readme-generator@1.7.1

Package Exports

github-action-readme-generator

Readme

# GitHub Action: 📓 GitHub Action's Readme Generator

Keep the README.md `usage`, `inputs` and `outputs` in sync with the `action.yml` file. Additionally the Action's usage example is updated to match the Action's current release.

This is a CLI tool and GitHub Action that reads the details from a GitHub Action's action.yml file. It updates the README.md file with the name, description, usage, inputs, outputs, and examples of the action. 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.

📝 This tool uses markdown comments as delimiting tokens within the README.md file to determine where to place the generated content.

🔗 You can find an example with all fields filled in, and no other free-form content, 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: ",
  "pretty": true
}

TODO

Add section for a title to the generator
Add section for a description to the generator
Add word wrapping to multi-line text
Add section to generate the action.yml inputs to a table to the generator
Add section to generate the action.yml outputs to a table to the generator
Add a markdown contents menu section to the generator
Allow for using a separate template for generating the readme file
Add section to embed other markdown files or directories by path, so that documentation can be organized in the file system.
i.e.,  and

Usage

- uses: bitflight-devops/github-action-readme-generator@v1.7.0
  with:
    # Default: action.yml
    action: ''

    # Default: README.md
    readme: ''

    owner: ''

    repo: ''

    save: ''

    pretty: ''

    versioning_enabled: ''

    version_override: ''

    # Default: v
    version_prefix: ''

    # Default: main
    versioning_default_branch: ''

    # Default: GitHub Action:
    title_prefix: ''

    # Default: true
    include_github_version_badge: ''

    # Default: .github/ghadocs/branding.svg
    branding_svg_path: ''

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. i.e: `bitflight-devops`\|`your-gh-username`		false
`repo`	The GitHub Action repository name. i.e: `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		false
`versioning_enabled`	Enable the update of the usage version to match the latest version in the `package.json` file		false
`version_override`	Set a specific version to display in the README.md		false
`version_prefix`	Prefix the version with this value (if it isn't already prefixed)	`v`	false
`versioning_default_branch`	If versioning is disabled show this branch instead	`main`	false
`title_prefix`	Add a prefix to the README title	`GitHub Action:`	false
`include_github_version_badge`	Include additional badge showing latest tag	`true`	false
`branding_svg_path`	Save and load the branding svg image in the README from this path	`.github/ghadocs/branding.svg`	false

github-action-readme-generator