|
| 1 | +--- |
| 2 | +pageClass: "rule-details" |
| 3 | +sidebarDepth: 0 |
| 4 | +title: "markdown-preferences/max-len" |
| 5 | +description: "enforce maximum length for various Markdown entities" |
| 6 | +--- |
| 7 | + |
| 8 | +# markdown-preferences/max-len |
| 9 | + |
| 10 | +> enforce maximum length for various Markdown entities |
| 11 | +
|
| 12 | +- ❗ <badge text="This rule has not been released yet." vertical="middle" type="error"> **_This rule has not been released yet._** </badge> |
| 13 | + |
| 14 | +## 📖 Rule Details |
| 15 | + |
| 16 | +This rule enforces a configurable maximum length for different Markdown entities such as headings, paragraphs, lists, blockquotes, tables, code blocks, frontmatter, footnote definitions, HTML blocks, and math blocks. |
| 17 | + |
| 18 | +Overly long Markdown elements reduce readability, make diffs harder to review, and complicate maintenance. By enforcing reasonable maximum lengths for various entities, documentation remains cleaner, easier to navigate, and more consistent across the project. |
| 19 | + |
| 20 | +<!-- prettier-ignore-start --> |
| 21 | + |
| 22 | +<!-- eslint-skip --> |
| 23 | + |
| 24 | +```md |
| 25 | +<!-- eslint markdown-preferences/max-len: ['error', { heading: 80, paragraph: 120 }] --> |
| 26 | + |
| 27 | +<!-- ✓ GOOD --> |
| 28 | + |
| 29 | +## This heading is within the limit |
| 30 | + |
| 31 | +This is a paragraph that fits comfortably within the specified maximum length limit. |
| 32 | + |
| 33 | +- A list item that is short enough |
| 34 | + |
| 35 | +<!-- ✗ BAD --> |
| 36 | + |
| 37 | +## This is a very long heading that exceeds the default eighty character maximum length |
| 38 | + |
| 39 | +This is an extremely long paragraph that goes on and on and on well beyond the one hundred and twenty character maximum length limit and should be broken up. |
| 40 | + |
| 41 | +- This is a very long list item that definitely exceeds the default one hundred and twenty character maximum length limit and should be reported |
| 42 | +``` |
| 43 | + |
| 44 | +<!-- prettier-ignore-end --> |
| 45 | + |
| 46 | +## 🔧 Options |
| 47 | + |
| 48 | +This rule accepts an object with the following properties: |
| 49 | + |
| 50 | +```json |
| 51 | +{ |
| 52 | + "markdown-preferences/max-len": [ |
| 53 | + "error", |
| 54 | + { |
| 55 | + "heading": 80, |
| 56 | + "paragraph": 120, |
| 57 | + "list": 120, |
| 58 | + "blockquote": 120, |
| 59 | + "table": 120, |
| 60 | + "footnoteDefinition": 120, |
| 61 | + "html": 120, |
| 62 | + "code": "ignore", |
| 63 | + "frontmatter": "ignore", |
| 64 | + "math": "ignore", |
| 65 | + "ignoreUrls": true |
| 66 | + } |
| 67 | + ] |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +### Entity Options |
| 72 | + |
| 73 | +These options control the maximum line length for specific Markdown entity types: |
| 74 | + |
| 75 | +- `heading` (default: `80`): Maximum line length for headings. Set to `"ignore"` to skip checking. |
| 76 | +- `paragraph` (default: `120`): Maximum line length for paragraphs. Set to `"ignore"` to skip checking. |
| 77 | +- `table` (default: `120`): Maximum line length for tables. Set to `"ignore"` to skip checking. |
| 78 | +- `html` (default: `120`): Maximum line length for HTML blocks. Set to `"ignore"` to skip checking. |
| 79 | +- `code` (default: `"ignore"`): Maximum line length for code blocks. Set to `"ignore"` to skip checking (recommended). See [notes on code blocks](#notes-on-code-blocks) below. |
| 80 | +- `frontmatter` (default: `"ignore"`): Maximum line length for frontmatter. Set to `"ignore"` to skip checking (recommended). |
| 81 | +- `math` (default: `"ignore"`): Maximum line length for math blocks. Set to `"ignore"` to skip checking. |
| 82 | + |
| 83 | +### Container Options |
| 84 | + |
| 85 | +These options control line length checking for entities within container elements. Containers can either have a simple numeric limit (applied to all nested content) or an object specifying different limits for different entity types within that container: |
| 86 | + |
| 87 | +- `list`: Override limits for content within lists. When not specified, nested content inherits from entity-level defaults. |
| 88 | +- `blockquote`: Override limits for content within blockquotes. When not specified, nested content inherits from entity-level defaults. |
| 89 | +- `footnoteDefinition`: Override limits for content within footnote definitions. When not specified, nested content inherits from entity-level defaults. |
| 90 | + |
| 91 | +#### Nested Configuration for Containers |
| 92 | + |
| 93 | +For `list`, `blockquote`, and `footnoteDefinition`, you can specify different limits for any entity types within these containers (including `heading`, `paragraph`, `table`, `html`, `math`, `code`, and `frontmatter`): |
| 94 | + |
| 95 | +```json |
| 96 | +{ |
| 97 | + "markdown-preferences/max-len": [ |
| 98 | + "error", |
| 99 | + { |
| 100 | + "heading": 80, |
| 101 | + "paragraph": 120, |
| 102 | + "table": 100, |
| 103 | + "blockquote": { |
| 104 | + "heading": 70, |
| 105 | + "paragraph": 100, |
| 106 | + "table": 90 |
| 107 | + } |
| 108 | + } |
| 109 | + ] |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +In this example: |
| 114 | + |
| 115 | +- Standalone headings are limited to 80 characters, but headings inside blockquotes are limited to 70 characters |
| 116 | +- Standalone tables are limited to 100 characters, but tables inside blockquotes are limited to 90 characters |
| 117 | +- All entity types (`heading`, `paragraph`, `table`, `html`, `math`, `code`, `frontmatter`) can be configured within containers |
| 118 | + |
| 119 | +### Language-specific Code Block Configuration |
| 120 | + |
| 121 | +For `code` and `frontmatter`, you can specify different limits per language: |
| 122 | + |
| 123 | +```json |
| 124 | +{ |
| 125 | + "markdown-preferences/max-len": [ |
| 126 | + "error", |
| 127 | + { |
| 128 | + "code": { |
| 129 | + "javascript": 100, |
| 130 | + "python": 80, |
| 131 | + "shell": "ignore" |
| 132 | + }, |
| 133 | + "frontmatter": { |
| 134 | + "yaml": 120, |
| 135 | + "toml": "ignore" |
| 136 | + } |
| 137 | + } |
| 138 | + ] |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +### URL Handling |
| 143 | + |
| 144 | +- `ignoreUrls` (default: `true`): When enabled, lines containing URLs are ignored. |
| 145 | + |
| 146 | +This option works similarly to [`@stylistic/eslint-plugin`'s `max-len` rule](https://eslint.style/rules/max-len#ignoreurls). |
| 147 | + |
| 148 | +### Notes on Code Blocks |
| 149 | + |
| 150 | +**Note:** Code blocks are ignored by default (`code: "ignore"`) because: |
| 151 | + |
| 152 | +1. Code inside code blocks should be linted using language-specific linters via ESLint's language plugins |
| 153 | +2. The [`@eslint/markdown`](https://github.com/eslint/markdown) plugin supports linting code blocks as their respective languages |
| 154 | +3. This rule cannot understand the syntax inside code blocks (e.g., comments, strings) |
| 155 | + |
| 156 | +If you need to enforce line length for code blocks in Markdown, you can: |
| 157 | + |
| 158 | +- Use the language-specific ESLint configuration for code blocks (recommended): |
| 159 | + |
| 160 | + ```js |
| 161 | + { |
| 162 | + files: ["**/*.md/*.js"], |
| 163 | + rules: { |
| 164 | + "@stylistic/max-len": ["error", { "ignoreComments": true }] |
| 165 | + } |
| 166 | + } |
| 167 | + ``` |
| 168 | + |
| 169 | + **However**, this feature is not currently available with this plugin. It may be possible in the future. The RFC is at: <https://github.com/eslint/rfcs/pull/105> |
| 170 | + |
| 171 | +- Set the `code` option to enforce a simple line length limit (not syntax-aware) |
| 172 | + |
| 173 | +For more information, see the [advanced configuration guide](https://github.com/eslint/markdown/blob/main/docs/processors/markdown.md#advanced-configuration). |
| 174 | + |
| 175 | +## 📚 Further Reading |
| 176 | + |
| 177 | +- [Markdownlint MD013](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md013.md) - Similar rule in markdownlint |
| 178 | +- [@stylistic/eslint-plugin max-len](https://eslint.style/rules/max-len) - ESLint stylistic rule for code |
| 179 | + |
| 180 | +## 👫 Related Rules |
| 181 | + |
| 182 | +- [no-multiple-empty-lines](./no-multiple-empty-lines.md) - Disallow multiple empty lines |
| 183 | + |
| 184 | +## 🔍 Implementation |
| 185 | + |
| 186 | +<!-- eslint-disable markdown-links/no-dead-urls -- Auto generated --> |
| 187 | + |
| 188 | +- [Rule source](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/blob/main/src/rules/max-len.ts) |
| 189 | +- [Test source](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/blob/main/tests/src/rules/max-len.ts) |
| 190 | +- [Test fixture sources](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/tree/main/tests/fixtures/rules/max-len) |
| 191 | + |
| 192 | +<!-- eslint-enable markdown-links/no-dead-urls -- Auto generated --> |
0 commit comments