github-action-readme-generator/action.yml

The docs generator for GitHub Actions. Auto-syncs action.yml to README.md with 8 sections: inputs, outputs, usage, badges, branding & more. Works as CLI or GitHub Action.

---
name: GitHub Action's Readme Generator
author: Jamie Nelson <jamie@bitflight.io>
description: 📓 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.

branding:
  icon: book-open
  color: yellow
inputs:
  action:
    description: |
      The absolute or relative path to the `action.yml` file to read in from.
    required: false
    default: action.yml
  readme:
    description: >
      The absolute or relative path to the markdown output file that
      contains the formatting tokens within it.
    required: false
    default: README.md
  owner:
    description: |
      The GitHub Action repository owner, this field is autodetected by default.
      Example: `bitflight-devops` or `your-gh-username`
    required: false
  repo:
    description: |
      The GitHub Action repository name, this field is autodetected by default.
      Example: `github-action-readme-generator`
    required: false
  save:
    description: |
      Save the provided values in a `.ghadocs.json` file.
      This will update any existing `.ghadocs.json` file that is in place.
    required: false
    default: false
  pretty:
    description: |
      Use `prettier` to pretty print the new README.md file
    required: false
    default: "true"
  versioning_enabled:
    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`
    required: false
    default: true
  version_override:
    description: >
      Set a specific version to display in the README.md, maybe you want
      to use a major or minor version
    required: false
  version_prefix:
    description: |
      Prefix the version with this value, if it isn't already prefixed
    required: false
    default: v
  versioning_default_branch:
    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`
    required: false
    default: main
  version_source:
    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
    required: false
    default: git-tag
  title_prefix:
    description: |
      Add a prefix to the README title.
      The title template looks like this:
      # {brand}{prefix}{title}
    required: false
    default: "GitHub Action: "
  include_github_version_badge:
    description: |
      Include additional badge showing latest tag
    required: false
    default: true
  branding_svg_path:
    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}
    required: false
    default: .github/ghadocs/branding.svg
  branding_as_title_prefix:
    default: true
    type: boolean
    description: >
      Prefix the title in the `<!-- start title -->` section with the svg
      branding image

      The title template looks like this:

      # {brand}{prefix}{title}
outputs:
  sections:
    description: |
      A json object containing a map of section names to their new content
  readme:
    description: |
      The path to the generated README.md file
  readme_before:
    description: |
      The content of the readme file before the changes were made
  readme_after:
    description: |
      The content of the readme file after the changes were made
runs:
  using: "node20"
  main: "./dist/bin/index.js"