@stephansama/auto-readme
Version:
Generate lists and tables for your README automagically based on your repository and comments
224 lines (163 loc) • 20.6 kB
Markdown
# Auto Readme 🪄
[](https://github.com/stephansama/packages/tree/main/core/auto-readme)
[](https://packages.stephansama.info/api/@stephansama/auto-readme)
[](https://www.npmjs.com/package/@stephansama/auto-readme)
[](https://www.npmjs.com/package/@stephansama/auto-readme)
Generate lists and tables for your README automagically based on your repository
##### Table of contents
<details><summary>Open Table of contents</summary>
- [Installation](#installation)
- [Usage](#usage)
- [CLI Options](#cli-options)
- [Configuration](#configuration)
- [Configuration File](#configuration-file)
- [JSON Example](#json-example)
- [YAML Example](#yaml-example)
- [JavaScript Example](#javascript-example)
- [TypeScript Example](#typescript-example)
- [Schema](#schema)
</details>
## Installation
```sh
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:
```sh
pnpx @stephansama/auto-readme [options]
```
To turn on table of content enable the setting `enableToc` and add the following header
```md
## Table of contents
```
To turn on the usage generator enable the setting `enableUsage` and add the following header
```md
## Usage
```
To use the zod generator add the following comments
```md
<!-- ZOD path="./path/to/zod.js" start -->
<!-- ZOD end -->
```
There are more [Actions](#actions) that you can use in conjunction with different [languages](#language) and [formats](#formats) like so:
```md
<!-- JS-WORKSPACE-TABLE start -->
<!-- JS-WORKSPACE-TABLE end -->
```
You can run `auto-readme` as a pre-commit git hook to automatically keep your `README`s up to date. For example, you can use `husky` to add the following to your `.husky/pre-commit` file:
```sh
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](#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](https://github.com/cosmiconfig/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
```json
{
"$schema": "./node_modules/@stephansama/auto-readme/config/schema.json",
"disableEmojis": true
}
```
#### YAML Example
```yaml
# yaml-language-server: $schema=./node_modules/@stephansama/auto-readme/config/schema.yaml
disableEmojis: true
```
#### JavaScript Example
```javascript
/** @type {import('@stephansama/auto-readme').Config} */
export default {
disableEmojis: true,
};
```
#### TypeScript Example
```typescript
import type { Config } from "@stephansama/auto-readme";
export default {
disableEmojis: true,
} satisfies Config;
```
### Schema
<!-- ZOD path="./src/schema.js" start -->
# 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](#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](#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:_<ul><li>`downloadImage`: `string`</li><li>`emojis`: `Record<'default' \| 'description' \| 'devDependency' \| 'downloads' \| 'name' \| 'private' \| 'required' \| 'version', string>` - Table heading emojis used when enabled</li><li>`registryUrl`: `string`</li><li>`versionImage`: `string`</li></ul> | `{"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'`
<!-- ZOD end -->