MDS001: line-length
Line exceeds maximum length.
# Settings
| Setting | Type | Default | Description |
|---|---|---|---|
max | int | 80 | Maximum allowed line length |
heading-max | int | – | Max length for heading lines; inherits max when unset |
code-block-max | int | – | Max length for code block lines; inherits max when unset |
stern | bool | false | Only flag long lines that contain a space past the limit |
exclude | list | ["code-blocks", "tables", "urls"] | Categories to exclude from checking |
reflow | bool | false | Auto-fix over-long prose paragraphs by rewrapping to max |
abbreviations | list | [] | Extra abbreviations the reflow fixer keeps unbroken |
Valid exclude values:
code-blocks– skip lines inside fenced or indented code blockstables– skip lines that are table rows (starting with|)urls– skip lines whose only content is a URL
Set exclude: [] to check everything (equivalent to the old strict: true).
The strict setting is deprecated. If present, strict: true is translated
to exclude: [] and strict: false to the default exclude list.
# Per-category limits
When heading-max is set, heading lines (ATX and Setext) use that
limit instead of max. When code-block-max is set, lines inside fenced or
indented code blocks use that limit instead of max. When either setting is
unset (absent), lines of that type inherit max.
Per-category limits and exclude compose.
A code block line excluded via exclude: [code-blocks] is still skipped,
even when code-block-max is set.
# Stern mode
When stern: true, a line that exceeds the active limit is flagged only if it
contains a space character at or beyond the limit column. Lines with no space
past the limit (for example a long URL at the end of a line) are allowed.
Stern mode applies independently of exclude. A line inside a code block that
is excluded via exclude: [code-blocks] is still skipped regardless of stern.
Stern uses the active max for each line type, so it respects heading-max and
code-block-max when set.
# Reflow (auto-fix)
By default the rule reports long lines but does not rewrite them: mdsmith fix
leaves prose untouched. Set reflow: true to opt into the auto-fix, which
rewraps over-long top-level prose paragraphs to fit within max.
Reflow is deliberately conservative. It rewraps only paragraphs that sit
directly in the document body and contain a flagged long line. It skips
headings, list items, block quotes, tables, generated sections, paragraphs that
carry a Markdown hard line break, and paragraphs that contain inline raw HTML.
Inline code spans are preserved verbatim, and a single word wider than max (a
long URL or link) keeps its own over-long line rather than being broken.
Wrapping is abbreviation-aware. It never ends a wrapped line on an abbreviation,
and it never splits a run of initials. So e.g. stays with the word it
introduces, and J. R. R. Tolkien is never broken across lines. Detection
reuses mdsmith’s trained abbreviation model — the same one the readability rules
use to split sentences. It recognises honorifics (Dr., Mr.), reference forms
(vs., No.), initials (J.), and dotted forms (e.g., i.e., U.S.A.). The
abbreviations setting adds project-specific entries the model does not know
(etc., approx.), and append-merges across config layers so a kind can extend
the inherited list without restating it.
The payoff is clearest at the wrap boundary. A naive word wrap of this line at 80 columns splits the spaced acronym across the break:
Historians traced the founding and the early constitutional debates of the U. S.
A. with real care.Reflow breaks before the acronym instead, keeping U. S. A. whole on one line:
Historians traced the founding and the early constitutional debates of the
U. S. A. with real care.Reflow keeps each paragraph whole. No line it writes starts a new block. This
holds for CommonMark and the extensions below, whatever markdown-flavor says:
- an ATX heading: one to six
#followed by a space, a tab, or the line end - a thematic break, such as
***,- - -, or_ _ _ - a code fence of 3 or more backticks or tildes, with or without an info string
- a block quote marker
> - a list marker
-,+,*,1., or1), even with nothing after it - an HTML block of types 1 to 6, such as
<div,<!--, or<?name - a setext underline: a line of only
=or only- - a GFM table delimiter row, such as
|-|-|,--- | ---, or:--|--: - a footnote definition
[^label]:, or a definition:then a space or tab
A bare list marker is paragraph text to CommonMark, but some renderers read it
as an empty list item. No line but the last ends in \, a hard line break.
Block starts of other extensions, such as a $$ math block or MyST’s %
comment, :::, +++, and (label)=, are not avoided.
If a plain word wrap would start a line with one of these, reflow moves the
word before it down to lead that line instead. At fifty columns, a plain wrap of
this paragraph starts its third line with > opens, a block quote. Reflow moves
with down to lead that line:
When writing Markdown, a line that starts with #
and a space opens a heading, one that starts
with > opens a block quote, and a line that begins
with 1. and a space starts a list.Text that only looks like block syntax wraps as usual, such as #48, #tag,
2., 1999., x = y, or a lone :. Reflow judges each line on its own, so a
table delimiter row counts even when the line before it has another cell count.
A paragraph that opens with [^1]: or : still wraps. Its marker keeps the
next word, its first line never forms a link reference definition, and no later
line starts with a list marker such as 2., which would open a list there.
A line runs past max only when no layout within max avoids these starts,
such as when the word before a marker already fills the line. That line then
takes as few extra words as it can. A run that reflow keeps together, such as
U. S. A., counts as one word. A paragraph is left as written when one of its
lines would need more than eight extra words, or when every layout starts a line
with block syntax. So is a paragraph with a line after its first that already
starts one, such as a definition under its term or a table without outer pipes.
# Config
Enable (default):
rules:
line-length:
max: 80
exclude:
- code-blocks
- tables
- urlsDisable:
rules:
line-length: falseCustom (per-category limits):
rules:
line-length:
max: 80
heading-max: 100
code-block-max: 120
exclude:
- tables
- urlsCustom (stern mode; allow long lines without spaces past the limit):
rules:
line-length:
max: 80
stern: trueCustom (check everything; no exclusions):
rules:
line-length:
max: 80
exclude: []Custom (enable the reflow auto-fix and add project abbreviations):
rules:
line-length:
max: 80
reflow: true
abbreviations:
- etc.
- approx.Custom (skip only code blocks and URLs; check tables):
rules:
line-length:
max: 120
exclude:
- code-blocks
- urls# Examples
# Bad
Line exceeds the default 80-character limit:
# Title
This line is deliberately made to exceed the eighty character limit by adding extra words here now.Line exceeds a custom max: 120 limit:
# Title
This line is deliberately made very long so that it exceeds the one hundred and twenty character limit set right here!!!!Heading exceeds heading-max: 60:
# This heading is deliberately made long enough to exceed sixty charsLong line with spaces past the limit (stern: true still flags it):
# Title
This line is deliberately made to exceed the eighty character limit by adding extra words here now.No exclusions — URLs and code blocks are also checked:
# Title
This line is deliberately made to exceed the eighty character limit by adding extra words here now.
https://example.com/this-is-a-very-long-url-that-exceeds-eighty-characters-and-should-be-flagged# Good
# Title
This line is well within the eighty character limit.Heading within heading-max: 100 (even though it exceeds max: 80):
# This heading is within the heading-max limit of one hundred charactersCode block within code-block-max: 120:
# Title
```text
This line inside a code block is over 80 characters but within the code-block-max limit of one hundred and twenty.
```# Meta-Information
- ID: MDS001
- Name:
line-length - Status: ready
- Default: enabled, max: 80
- Fixable: yes (opt-in via
reflow) - Implementation: source
- Category: line
- markdownlint: MD013 (line-length)
- rumdl: MD013 (line-length)
- mado: MD013 (line-length)
- gomarklint: max-line-length