Home

Awesome

eslint-doc-generator<!-- omit from toc -->

npm version test coverage

Automatic documentation generator for ESLint plugins and rules. Inspired by documentation conventions from ESLint and top ESLint plugins.

Generates the following documentation covering a wide variety of rule metadata:

Also performs configurable section consistency checks on rule docs:

Table of contents<!-- omit from toc -->

Motivation

Setup

Install it:

npm i --save-dev eslint-doc-generator

Scripts

Add scripts to package.json:

{
  "scripts": {
    "lint": "npm-run-all \"lint:*\"",
    "lint:docs": "markdownlint \"**/*.md\"",
    "lint:eslint-docs": "npm run update:eslint-docs -- --check",
    "lint:js": "eslint .",
    "update:eslint-docs": "eslint-doc-generator"
  }
}

Update README.md

Delete any old rules list from your README.md. A new one will be automatically added to your ## Rules section (along with the following marker comments if they don't already exist):

<!-- begin auto-generated rules list -->
<!-- end auto-generated rules list -->

Optionally, add these marker comments to your README.md in a ## Configs section or similar location (uses the meta.docs.description property exported by each config if available):

<!-- begin auto-generated configs list -->
<!-- end auto-generated configs list -->

Update rule docs

Delete any old recommended/fixable/etc. notices from your rule docs. A new title and notices will be automatically added to the top of each rule doc (along with a marker comment if it doesn't already exist).

<!-- end auto-generated rule header -->

Optionally, add these marker comments to your rule docs in an ## Options section or similar location:

<!-- begin auto-generated rule options list -->
<!-- end auto-generated rule options list -->

Note that rule option lists are subject-to-change as we add support for more kinds and properties of schemas. To fully take advantage of them, you'll want to ensure your rules have the meta.schema property fleshed out with properties like description, type, enum, default, required, deprecated.

Configure linting

And be sure to enable the recommended rules from eslint-plugin-eslint-plugin as well as:

Usage

Run the script from package.json to start out or any time you add a rule or update rule metadata in your plugin:

npm run update:eslint-docs

Examples

For examples, see our users or the in-house examples below. Note that the in-house examples intentionally show all possible columns and notices.

Rules list table

See the generated rules table and legend in our example README.md.

Configs list table

See the generated configs table in our example README.md.

Rule doc notices

See the generated rule doc title and notices in our example rule docs no-foo.md, prefer-bar.md, require-baz.md.

Rule doc options lists

See the generated rule doc options lists in our example rule doc no-foo.md.

Users

This tool is used by popular ESLint plugins like:

Configuration options

These can be provided as CLI options or as config file options. All options are optional.

The CLI has an optional path argument if you need to point the CLI to an ESLint plugin directory that isn't just the current directory:

eslint-doc-generator path/to/eslint-plugin

There's also a postprocess option that's only available via a config file.

NameDescription Default
--checkWhether to check for and fail if there is a diff. Any diff will be displayed but no output will be written to files. Typically used during CI.false
--config-emojiCustom emoji to use for a config. Format is config-name,emoji. Option can be repeated.Default emojis are provided for common configs. See Badges for an alternative to emojis.
--config-formatThe format to use for config names. See choices in below table.name
--ignore-configConfig to ignore from being displayed. Often used for an all config. Option can be repeated.
--ignore-deprecated-rulesWhether to ignore deprecated rules from being checked, displayed, or updated.false
--init-rule-docsWhether to create rule doc files if they don't yet exist.false
--path-rule-docPath to markdown file for each rule doc. Use {name} placeholder for the rule name. A function can also be provided for this option via a config file.docs/rules/{name}.md
--path-rule-listPath to markdown file where the rules table list should live. Option can be repeated.README.md
--rule-doc-noticesOrdered, comma-separated list of notices to display in rule doc. Non-applicable notices will be hidden. See choices in below table.deprecated, configs, fixableAndHasSuggestions, requiresTypeChecking
--rule-doc-section-excludeDisallowed section in each rule doc. Exit with failure if present. Option can be repeated.
--rule-doc-section-includeRequired section in each rule doc. Exit with failure if missing. Option can be repeated.
--rule-doc-section-optionsWhether to require an "Options" or "Config" rule doc section and mention of any named options for rules with options.true
--rule-doc-title-formatThe format to use for rule doc titles. See choices in below table.desc-parens-prefix-name
--rule-list-columnsOrdered, comma-separated list of columns to display in rule list. Empty columns will be hidden. See choices in below table.name, description, configsError, configsWarn, configsOff, fixable, hasSuggestions, requiresTypeChecking, deprecated
--rule-list-splitRule property(s) to split the rules list by. A separate list and header will be created for each value. Example: meta.type. A function can also be provided for this option via a config file.
--url-configsLink to documentation about the ESLint configurations exported by the plugin.
--url-rule-docLink to documentation for each rule. Useful when it differs from the rule doc path on disk (e.g. custom documentation site in use). Use {name} placeholder for the rule name. A function can also be provided for this option via a config file.

Column and notice types

These are the types of rule metadata that are available for display in rule list columns (--rule-list-columns) and/or rule doc notices (--rule-doc-notices).

EmojiTypeColumn?Notice?Description
💼configsErrorYesNoWhether a rule is set to error in a config.
🚫configsOffYesNoWhether a rule is set to off in a config.
⚠️configsWarnYesNoWhether a rule is set to warn in a config.
💼configsNoYesWhat configs set a rule to what severities.
deprecatedYesYesWhether a rule is deprecated (i.e. likely to be removed/renamed in a future major version).
descriptionYesYesThe rule description.
🔧💡fixableAndHasSuggestionsYesYesWhether a rule is fixable and/or has suggestions.
🔧fixableYesYesWhether a rule is fixable.
💡hasSuggestionsYesYesWhether a rule has suggestions.
nameYesNoThe rule name.
⚙️optionsYesYesWhether a rule has options.
💭requiresTypeCheckingYesYesWhether a rule requires type checking.
🗂️typeYesYesThe rule type (problem, suggestion, or layout).

--config-format

Where recommended is the config name and eslint-plugin-test is the plugin name.

ValueExample
name (default)recommended
plugin-colon-prefix-nameplugin:test/recommended
prefix-nametest/recommended

--rule-doc-title-format

Where no-foo is the rule name, Disallow use of foo is the rule description, and eslint-plugin-test is the plugin name.

ValueExample
desc# Disallow use of foo
desc-parens-name# Disallow use of foo (no-foo)
desc-parens-prefix-name (default)# Disallow use of foo (test/no-foo)
name# no-foo
prefix-name# test/no-foo

Configuration file

There are a few ways to create a config file (as an alternative to passing the options via CLI):

Config files support all the CLI options but in camelCase.

Some options are exclusive to a JavaScript-based config file:

Example .eslint-doc-generatorrc.js:

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  ignoreConfig: ['all'],
};

module.exports = config;

Example .eslint-doc-generatorrc.js with pathRuleDoc function:

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  pathRuleDoc(name) {
    // e.g. rule name format is `some-plugin/some-rule`, and rule is in a monorepo under different package.
    const [plugin, rule] = name.split("/");
    return `packages/eslint-plugin-${plugin}/src/rules/${rule}.md`;
  },
};

module.exports = config;

Example .eslint-doc-generatorrc.js with ruleListSplit function:

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  ruleListSplit(rules) {
    return [
      {
        // No header for this list.
        rules: rules.filter(([name, rule]) => !rule.meta.someProp),
      },
      {
        title: 'Foo',
        rules: rules.filter(([name, rule]) => rule.meta.someProp === 'foo'),
      },
      {
        title: 'Bar',
        rules: rules.filter(([name, rule]) => rule.meta.someProp === 'bar'),
      },
    ];
  },
};

module.exports = config;

Example .eslint-doc-generatorrc.js with urlRuleDoc function:

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  urlRuleDoc(name, page) {
    if (page === 'README.md') {
      // Use URLs only in the readme.
      return `https://example.com/rules/${name}.html`;
    }
  },
};

module.exports = config;

Badges

While emojis are the recommended representations of configs that a rule belongs to, you can alternatively use a text/image/icon badge for configs by supplying the following markdown for the emoji using the --config-emoji option.

For example, here's the markdown for a text badge representing a custom fun config that displays in blue (note that the markdown includes alt text followed by the image URL):

![fun config badge](https://img.shields.io/badge/-fun-blue.svg)

Here's how you'd configure it:

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  configEmoji: [
    ['fun', '![fun config badge](https://img.shields.io/badge/-fun-blue.svg)'],
  ],
};

module.exports = config;

And how it looks:

fun config badge

Compatibility

Build tools

If you have a build step for your code like Babel or TypeScript, you may need to adjust your scripts to run your build before this tool to ensure the documentation is generated from the latest plugin information:

{
  "build": "tsc",
  "update:eslint-docs": "npm run build && eslint-doc-generator"
}

markdownlint

The output of this tool should be compatible with the default configuration of markdownlint, which you might use to lint your markdown. If it's not, you can follow the prettier example to tweak your scripts or use the postprocess option. See here for an example of markdownlint's Node API for applying fixes to use in your postprocess function.

prettier

If you use prettier to format your markdown, you can provide a postprocess function to ensure the documentation generated by this tool is formatted correctly:

const prettier = require('prettier');
const { prettier: prettierRC } = require('./package.json'); // or wherever your prettier config lies

/** @type {import('eslint-doc-generator').GenerateOptions} */
const config = {
  postprocess: (content, path) =>
    prettier.format(content, { ...prettierRC, parser: 'markdown' }),
};

module.exports = config;

Alternatively, you can configure your scripts to run prettier after this tool:

{
  "format": "prettier --write .",
  "lint:eslint-docs": "npm run update:eslint-docs && git diff --exit-code",
  "update:eslint-docs": "eslint-doc-generator && npm run format"
}

Semantic versioning policy

This tool follows semantic versioning.

New features will be released as a minor version, while bug fixes will be released as a patch version.

Breaking changes will be released as a major version and include:

Tweaks to the generated documentation output can take place in any type of release including minor and patch versions. This can break your build, as even a small formatting change will cause a diff, but you can simply re-run the tool to fix.

Related