auto-readme

auto-readme

Keeps README files up to date by replacing content between HTML comment markers. Run manually, in CI, or as a pre-commit hook.

Comment syntax

<!-- ACTION_TYPE [options] start -->
<!-- ACTION_TYPE end -->

Content between markers is replaced on every run. Markers must be paired — every start needs a matching end.

Setup

pnpx @stephansama/auto-readme

Add configuration to package.json:

{
  "auto-readme": {
    "disableEmojis": false,
    "onlyShowPublicPackages": true
  }
}

Or use a standalone config file (.autoreadmerc.json, .config/autoreadmerc.ts, autoreadme.config.ts, etc.).

Core Patterns

Monorepo workspace table

<!-- WORKSPACE start -->
<!-- WORKSPACE end -->

Generates a table of all packages in the workspace with name, version badge, download badge, and description. Reads from the pnpm/npm workspace config.

GitHub Action inputs table

<!-- ACTION start -->
<!-- ACTION end -->

Place this comment in a README inside a directory that contains action.yml or action.yaml. Generates a table of action inputs with name, required, default, and description columns.

Package.json dependency table

<!-- PKG start -->
<!-- PKG end -->

Generates a table of dependencies and devDependencies from the nearest package.json. Pass path= to point to a different package.json:

<!-- PKG path="../other-package" start -->
<!-- PKG end -->

Zod schema reference table

<!-- ZOD path="./src/schema.js" start -->
<!-- ZOD end -->

Generates a markdown reference table from the default export of the given file using zod2md. The path= parameter is required and must point to a file with a zod schema as its default export.

Pre-commit hook (changed files only)

# .husky/pre-commit
auto-readme --changes

--changes (-g) only processes README files that are modified in the current git changeset. Use in pre-commit hooks to avoid re-processing the entire repo on every commit.