eslint-plugin-doc-code-blocks

0.3.1 verified Fri May 01 auth: no javascript maintenance

Lint JavaScript code embedded in block comments (e.g., JSDoc, YUIDoc code fences) using ESLint. Version 0.3.1 is the latest stable release; the package has low release cadence and is in maintenance mode. It does not provide its own rules but leverages existing ESLint configurations (eslint:recommended or eslint:all) on code blocks within comments. A key differentiator is enabling code quality checks on documentation examples, though it lacks active development and may not support ESLint versions beyond 8.x.

Common errors

error Error: Failed to load plugin 'doc-code-blocks' declared in '.eslintrc.js': Cannot find module 'eslint-plugin-doc-code-blocks' ↓

cause Plugin not installed globally when ESLint is global.

fix

Install the plugin globally: npm i -g eslint-plugin-doc-code-blocks

error Error: Configuration for rule 'semi' is invalid: Value '"always"' is the wrong type (expected object or boolean) ↓

cause Using 'extends' from doc-code-blocks/all without proper rule config format.

fix

Ensure rule values are valid ESLint rule severity (e.g., 'error', 2) or an array: 'semi': ['error', 'always']

error Parsing error: The keyword 'import' is reserved ↓

cause Source code in the code block uses ES modules, but ESLint parser is not set to 'eslint:recommended' or parserOptions for modules.

fix

Set parserOptions: { 'sourceType': 'module' } in your .doc.eslintrc.js.

Warnings

deprecated This plugin does not provide its own rules and relies on ESLint's built-in configs (eslint:all, eslint:recommended). It may not work with ESLint >=9.x due to flat config migration. ↓

fix Consider using '@eslint/plugin-markdown' or 'eslint-plugin-markdown' for similar functionality with better maintenance.

breaking ESLint's 'eslint:all' config can break across minor releases; plugin extends 'all' in 'plugin:doc-code-blocks/all'. ↓

fix Prefer 'plugin:doc-code-blocks/recommended' which uses 'eslint:recommended', or define explicit rules.

gotcha Rules are applied to code blocks only when using a separate config file; rules in the default .eslintrc do not affect code blocks. ↓

fix Always run eslint with a dedicated config for code blocks (e.g., --config .doc.eslintrc.js).

gotcha The plugin does not support ESLint flat config (eslint.config.js). Only legacy .eslintrc format is supported. ↓

fix Continue using .eslintrc.* files; plugin will not work with flat config introduced in ESLint 9.

Install

npm install eslint-plugin-doc-code-blocks

yarn add eslint-plugin-doc-code-blocks

pnpm add eslint-plugin-doc-code-blocks

Imports

plugin
wrong
```
plugins: ['eslint-plugin-doc-code-blocks']
```
correct
```
plugins: ['doc-code-blocks']
```
ESLint plugin names omit the 'eslint-plugin-' prefix in config files.
config
wrong
```
extends: ['doc-code-blocks/recommended']
```
correct
```
extends: ['plugin:doc-code-blocks/recommended']
```
Configs must include 'plugin:' prefix to reference plugin-provided configs.
CLI
wrong
```
eslint -c doc-code-blocks your_files
```
correct
```
eslint --config .doc.eslintrc.js your_files
```
Use a separate config file (e.g., .doc.eslintrc.js) to apply rules to code blocks.

Quickstart

Configures the plugin and a separate config to lint code blocks with custom rules, then runs eslint with that config.

// .eslintrc.js
module.exports = {
  plugins: ['doc-code-blocks'],
};

// .doc.eslintrc.js
module.exports = {
  extends: ['plugin:doc-code-blocks/recommended'],
  plugins: ['doc-code-blocks'],
  rules: {
    'semi': ['error', 'always'],
    'no-console': 'off'
  }
};

// Run:
// eslint --config .doc.eslintrc.js --no-eslintrc --ext .js .