@stephansama packages / @stephansama/auto-readme

Auto Readme 🪄

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

Table of contents

Open 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
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 of Headings items (optional)	{"ACTION":["name","required","default","description"],"PKG":["name","version","devDependency"],"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: string emojis: Object with dynamic keys of type Headings and values of type string - Table heading emojis used when enabled registryUrl: string versionImage: string	{"downloadImage":"https://img.shields.io/npm/dw/?labelColor=211F1F","emojis":{"default":"⚙️","description":"📝","devDependency":"💻","downloads":"📥","name":"🏷️","private":"🔒","required":"","version":""},"registryUrl":"https://www.npmjs.com/package/","versionImage":"https://img.shields.io/npm/v/?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' (optional)

Default value: 'TABLE'

Headings

Table heading options

Enum, one of the following possible values:

• 'default'
• 'description'
• 'devDependency'
• 'downloads'
• 'name'
• 'private'
• 'required'
• 'version'

Language

Enum, one of the following possible values:

• 'JS'
• 'RS' (optional)

Default value: 'JS'

TableHeadings

Table heading action configuration

Object record with dynamic keys:

• keys of type Actions
• values of type Array of Headings items (optional) (optional)

Default value: {"ACTION":["name","required","default","description"],"PKG":["name","version","devDependency"],"WORKSPACE":["name","version","downloads","description"],"ZOD":[]}

Templates

Object containing the following properties:

Property	Description	Type	Default
downloadImage		string	'https://img.shields.io/npm/dw/?labelColor=211F1F'
emojis	Table heading emojis used when enabled	Object with dynamic keys of type Headings and values of type string	{"default":"⚙️","description":"📝","devDependency":"💻","downloads":"📥","name":"🏷️","private":"🔒","required":"","version":""}
registryUrl		string	'https://www.npmjs.com/package/'
versionImage		string	'https://img.shields.io/npm/v/?logo=npm&logoColor=red&color=211F1F&labelColor=211F1F'

All properties are optional.

Modules

Module	Description
args	‐
comment	‐
config	‐
data	‐
index	‐
log	‐
pipeline	‐
plugin	‐
schema	‐
utils	‐