Auto Readme 🪄

Generate lists and tables for your README automagically based on your repository

Table of contents

• Installation
• Usage
• CLI Options
• Configuration
  • Configuration File
    • JSON Example
    • YAML Example
    • JavaScript Example
    • TypeScript Example
  • Schema

Installation

pnpm install @stephansama/auto-readme

Usage

In order to run the script you need to do two things

1. Create either a heading or a comment to enable the corresponding feature
2. Run the following command:

pnpx @stephansama/auto-readme [options]

To turn on table of content enable the setting enableToc and add the following header

## Table of contents

To turn on the usage generator enable the setting enableUsage and add the following header

## Usage

To use the zod generator add the following comments

<!-- ZOD path="./path/to/zod.js" start -->
<!-- ZOD end -->

There are more Actions that you can use in conjunction with different languages and formats like so:

<!-- JS-WORKSPACE-TABLE start -->
<!-- JS-WORKSPACE-TABLE end -->

You can run auto-readme as a pre-commit git hook to automatically keep your READMEs up to date. For example, you can use husky to add the following to your .husky/pre-commit file:

auto-readme -g

This will run auto-readme only when affected README files are changed

CLI Options

| Option | Alias | Description | Type | Default | | :---------- | :---- | :-------------------------------------------- | :-------- | :------ | | --changes | -g | Check only changed git files | boolean | false | | --check | -k | Do not write to files. Only check for changes | boolean | false | | --config | -c | Path to config file | string | | | --verbose | -v | whether or not to display verbose logging | boolean | false |

Most of the options in the schema below can also be used as command-line flags.

Configuration

auto-readme can be configured using a variety of files, such as package.json with an auto-readme property, or a standalone .autoreadmerc file. For more information on configuration files, see cosmiconfig.

Configuration File

You can configure auto-readme by creating a configuration file (or object) in the root of your project. The following file formats are supported:

• package.json
• .autoreadmerc.cjs
• .autoreadmerc.js
• .autoreadmerc.json
• .autoreadmerc.mjs
• .autoreadmerc.toml
• .autoreadmerc.ts
• .autoreadmerc.yaml
• .autoreadmerc.yml
• .autoreadmerc
• .config/.autoreadmerc.json
• .config/.autoreadmerc.toml
• .config/.autoreadmerc.yaml
• .config/.autoreadmerc.yml
• .config/.autoreadmerc
• .config/autoreadmerc.cjs
• .config/autoreadmerc.js
• .config/autoreadmerc.json
• .config/autoreadmerc.mjs
• .config/autoreadmerc.toml
• .config/autoreadmerc.ts
• .config/autoreadmerc.yaml
• .config/autoreadmerc.yml
• .config/autoreadmerc
• autoreadme.config.cjs
• autoreadme.config.js
• autoreadme.config.mjs
• autoreadme.config.ts

JSON Example

{
  "$schema": "./node_modules/@stephansama/auto-readme/config/schema.json",
  "disableEmojis": true
}

YAML Example

# yaml-language-server: $schema=./node_modules/@stephansama/auto-readme/config/schema.yaml
disableEmojis: true

JavaScript Example

/** @type {import('@stephansama/auto-readme').Config} */
export default {
  disableEmojis: true,
};

TypeScript Example

import type { Config } from "@stephansama/auto-readme";

export default {
  disableEmojis: true,
} satisfies Config;

Schema

Zod Schema

Actions

Comment action options

Enum, one of the following possible values:

• 'ACTION'
• 'PKG'
• 'USAGE'
• 'WORKSPACE'
• 'ZOD'

Config

Object containing the following properties:

| Property | Description | Type | Default | | :------------------------ | :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | affectedRegexes | | Array<string> | [] | | collapseHeadings | | Array<string> | [] | | defaultLanguage | Default language to infer projects from | Language | | | disableEmojis | Whether or not to use emojis in markdown table headings | boolean | false | | disableMarkdownHeadings | Whether or not to display markdown headings | boolean | false | | enablePrettier | Whether or not to use prettier to format the files | boolean | true | | enableToc | generate table of contents for readmes | boolean | false | | enableUsage | Whether or not to enable usage plugin | boolean | false | | headings | List of headings for different table outputs | Object with dynamic keys of type Actions and values of type Array<'default' \| 'description' \| 'devDependency' \| 'downloads' \| 'name' \| 'private' \| 'required' \| 'version'> (optional) | {"ACTION":["name","required","default","description"],"PKG":["name","version","devDependency"],"USAGE":[],"WORKSPACE":["name","version","downloads","description"],"ZOD":[]} | | onlyReadmes | Whether or not to only traverse readmes | boolean | true | | onlyShowPublicPackages | Only show public packages in workspaces | boolean | false | | removeScope | Remove common workspace scope | string | '' | | templates | Handlebars templates used to fuel list and table generation | Object with properties:downloadImage: stringemojis: Record<'default' \| 'description' \| 'devDependency' \| 'downloads' \| 'name' \| 'private' \| 'required' \| 'version', string> - Table heading emojis used when enabledregistryUrl: stringversionImage: string | {"downloadImage":"https://img.shields.io/npm/dw/{{name}}?labelColor=211F1F","emojis":{"default":"⚙️","description":"📝","devDependency":"💻","downloads":"📥","name":"🏷️","private":"🔒","required":"","version":""},"registryUrl":"https://www.npmjs.com/package/{{name}}","versionImage":"https://img.shields.io/npm/v/{{uri_name}}?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F"} | | tocHeading | Markdown heading used to generate table of contents | string | 'Table of contents' | | usageFile | Workspace level usage file | string | '' | | usageHeading | Markdown heading used to generate usage example | string | 'Usage' | | verbose | whether or not to display verbose logging | boolean | false |

All properties are optional. (optional)

Formats

Enum, one of the following possible values:

• 'LIST'
• 'TABLE'

Default value: 'TABLE'

Language

Enum, one of the following possible values:

• 'JS'
• 'RS'

Default value: 'JS'