Skip to main content

textlint v16.0.0

· 14 min read
azu
textlint creator

We are pleased to announce the release of textlint v16.0.0. This is a small major release: it requires Node.js 22.12, replaces the Markdown parser with a faster in-house parser, and makes the built-in plugins ESM-only.

Most users only need to update Node.js. This post first describes the changes for users who run textlint, and then the changes for developers of rules, plugins, and tools.

Summary​

For users:

  • Node.js 22.12.0 or later is required. Node.js 20 reached end-of-life. Update Node.js in your environment and CI.
  • Markdown parsing is much faster. textlint parses Markdown with a new in-house parser, and installs 59 third-party packages instead of 139 in v15.8.0. Rules report the same errors for most documents.
  • The node type of YAML front matter is renamed from Yaml to yaml. If your configuration lists "Yaml", such as in textlint-filter-rule-node-types, change it to "yaml". Otherwise front matter is checked as prose.
  • The output of some formatters changes slightly. table no longer throws on a tab in a message, and pretty-error no longer prints undefined for an empty file.
  • New options. --cache-strategy content detects changed files by content, --stdin works with the pretty-error and diff formatters, and the Markdown plugin's cjkFriendlyEmphasis recognizes emphasis in CJK text such as **強調。**この文.

For rule and plugin developers:

textlint started writing down its specifications, which were ambiguous, as Requirements and Design documents. While writing them, we made the ambiguous parts of TxtAST stricter. Most of the changes below come from this work.

  • @textlint/textlint-plugin-markdown and @textlint/textlint-plugin-text are ESM-only. Code that loads them directly with require() gets the module namespace, so use require(...).default or import.
  • @textlint/markdown-to-ast is a new CommonMark 0.31.2 + GFM parser. The AST is compatible. It differs only in edge cases where the new parser follows CommonMark and GitHub, and the hidden position property is removed.
  • Node types that are not in @textlint/ast-node-types are lowercase. Front matter and footnote references are not part of CommonMark or GFM, so Yaml, Toml, Json, and FootnoteReference become yaml, toml, json, and footnoteReference. The casing tells whether a node type is shared by all formats (TxtAST Requirements: Extension nodes).
  • Lines end with LF, CR, or CRLF in every format. U+2028 and U+2029 are no longer line endings in messages, and a lone CR is a line ending in plain text (TxtAST Requirements: Lines).
  • The plain text parser keeps one Paragraph per line. Every line ending at the end of the text becomes a Break, and a BOM is no longer included in the first Str (Plain text parsing Requirements).
  • @textlint/ast-tester checks that raw, range, and loc agree. Tests of a rule can fail if your plugin produces an AST that breaks the conventions (TxtAST Requirements: Checking an AST).
  • Deprecated type re-exports are removed from @textlint/kernel. Import the types from @textlint/types.
  • Formatters receive the source text through a getSource option. API users can pass in-memory text to loadFormatter().

For Users​

Node.js 22.12+ Required​

textlint v16 requires Node.js 22.12.0 or later, because Node.js 20 reached end-of-life on 2026-04-30.

Migration Required:

  • Update your Node.js version to 22.12.0 or later
  • Update your CI and Docker images to use Node.js 22.12+

#2182, #2201

Faster Markdown parsing​

textlint v16 parses Markdown with a new in-house parser instead of remark. It supports the same syntax as before: CommonMark, GFM (tables, strikethrough, task list items, autolink literals, footnotes), Pandoc-style inline notes (^[note]), and YAML/TOML/JSON front matter.

Parsing time with Node.js 22:

DocumentsBeforev16
js-primer (88 .md files, 1.4 MB)1,070 ms (v15.8.0)18 ms (about 58x faster)
3,189 real-world .md files (15.3 MB)18,506 ms (remark-based parser)about 400 ms (about 45x faster)

Inputs that took tens of seconds, such as a table with 20,000 rows, are parsed in milliseconds, and documents nested deeper than 100 levels are linted instead of throwing RangeError. @textlint/markdown-to-ast has no third-party dependencies, instead of 96 packages (7.5 MB).

textlint installs 59 third-party packages in production, instead of 139 in v15.8.0 (-80). The new parser, the in-house formatter helpers (#2183), the removal of unused dependencies (#2184), and the in-house line table of the kernel (#2199) removed them.

How much faster the textlint CLI finishes depends on how much of the time rules take:

ProjectBeforev16
webpack-book (62 files, 489 KB)1,448 ms (remark-based parser)949 ms (-34%)
magi-hacker (5 files, 5.5 KB)632 ms (remark-based parser)505 ms (-20%)
js-primer (60 files, with its own rules)18.7 s (v15.8.0)18.9 s (no change)

In js-primer, almost all of the time is spent in rules, such as the morphological analysis of Japanese text, so a faster parser does not change the total.

Rules report the same errors for most documents. A few edge cases follow CommonMark and GitHub more closely. For example, when a document starts with --- that is not a front matter fence, the lists in the document are now recognized. Another example is a footnote definition followed by link reference definitions without a blank line. The following lines are now part of the footnote, the same as micromark and the latest remark-gfm, so add a blank line after the footnote definition. See New Markdown parser for the details.

#2188

Front matter node type is yaml​

The node types of front matter and footnote references are renamed to lowercase: Yaml, Toml, Json, FootnoteReference → yaml, toml, json, footnoteReference.

If your configuration lists "Yaml" among node types to ignore, such as in the options of a filter rule or a rule, front matter is checked as prose in v16 without any error.

Migration Required (only if your configuration lists these node types):

Use "yaml" instead, or both names to support v15 and v16.

{
"filters": {
"node-types": {
"nodeTypes": ["yaml"]
}
}
}

#2188

Formatter output changes​

The output of the formatters is the same in most cases, with these differences:

  • table: a message that contains a control character such as a tab no longer throws an error
  • table: escape sequences in a message or a rule id are removed in the table cells. Without color, the output is the same as before
  • pretty-error: a message in an empty file no longer prints undefined
  • Column widths of some emoji follow newer Unicode data

#2183, #2180

Line endings in rare documents​

textlint counts lines by LF, CR, and CRLF in every format, the same as CommonMark, editors, and the Language Server Protocol. The line and column of errors change only for documents that contain a lone CR or U+2028/U+2029.

#2197, #2199

--cache-strategy​

--cache-strategy content detects changed files by their content hash instead of mtime and size, which is reliable in CI. The default is metadata, the same behavior as before.

textlint --cache --cache-strategy content "docs/**/*.md"

#2096

--stdin with pretty-error and diff​

textlint --stdin --format pretty-error now shows the code frame of the stdin text, and textlint --fix --stdin --format diff shows the diff of the stdin text.

#2186

cjkFriendlyEmphasis option of the Markdown plugin​

CommonMark does not recognize some emphasis in Chinese, Japanese, and Korean text, such as **強調。**この文, because a punctuation mark is inside the closing ** and a letter follows it. The new cjkFriendlyEmphasis option parses emphasis, strong emphasis, and strikethrough with the CommonMark CJK-friendly Amendments, the same as VitePress and Rspress. It is disabled by default. Enable it when your documents are rendered with these rules.

{
"plugins": {
"@textlint/markdown": {
"cjkFriendlyEmphasis": true
}
}
}

The AST does not record this option. A rule whose fixes depend on it needs its own cjkFriendlyEmphasis option, so enable both. For example, ja-space-around-strong and ja-space-around-emphasis of textlint-rule-preset-ja-spacing add the option in textlint-ja/textlint-rule-preset-ja-spacing#144.

#2203

Bug Fixes​

  • TIMING=1 reports each rule's own time instead of including other rules' time #2189
  • A relative --rules-base-directory is resolved from the current directory #2190
  • The github formatter escapes workflow command values #2159
  • The MCP server marks its tools as read-only #2136

For Rule and Plugin Developers​

Specifications of TxtAST and the parsers​

textlint started writing down its specifications, which were ambiguous, as Requirements and Design documents under docs/products/. The TxtAST Requirements define what rules can rely on in every format, and the Markdown parsing and plain text parsing Requirements define the AST of each format.

While writing them, we made the ambiguous parts of TxtAST stricter:

  • Node types that are not in @textlint/ast-node-types are lowercase
  • Lines end with LF, CR, or CRLF in every format
  • raw, range, and loc of a node agree with each other, and @textlint/ast-tester checks it

The breaking changes in this section come from these rules.

#2192

Built-in plugins are ESM-only​

@textlint/textlint-plugin-markdown and @textlint/textlint-plugin-text are now ESM-only packages. textlint, textlint-tester, and @textlint/legacy-textlint-core stay CommonJS and load them with dynamic import(), so you do not need to change anything if you use textlint through them. Node.js 22.12.0 enables require(esm) by default, so CommonJS code can also require() them.

Migration Required (only if you load a built-in plugin directly):

// Before
const markdownPlugin = require("@textlint/textlint-plugin-markdown");

// After (CommonJS): require() returns the module namespace
const { default: markdownPlugin } = require("@textlint/textlint-plugin-markdown");

// After (ESM)
import markdownPlugin from "@textlint/textlint-plugin-markdown";

#2109

New Markdown parser​

@textlint/markdown-to-ast no longer uses remark. It is now an in-house CommonMark 0.31.2 + GFM parser that creates TxtAST directly.

The output AST is the same as the remark-based parser of v16 development for all existing fixtures, all CommonMark and GFM spec examples, and thousands of real-world Markdown files. The differences are in edge cases, where the new parser follows CommonMark and GitHub:

  • When a document starts with --- (a thematic break) that is not a front matter fence, lists in the document are now recognized
  • loc of the text after a task list checkbox and a line ending now matches its range
  • A list item that ends with an unclosed fenced code block no longer overlaps the next item
  • A few positions of nodes with trailing whitespace inside nested containers with tabs

The Markdown AST also changed compared with v15 because of the remark upgrade in #2109. If your rule depends on the exact AST, please check it with v16.

The hidden position property (unist compatibility) is removed from nodes. Use range and loc.

Nesting deeper than 100 levels is not parsed as syntax. Block quotes and list items beyond the limit, and emphasis or links beyond 100 inline levels, stay as text.

#2188

Renamed node types​

Node types that are defined in @textlint/ast-node-types use PascalCase, and other node types use lowercase. Front matter and footnotes are not part of CommonMark or the GFM specification and are not in @textlint/ast-node-types, so their node types are now lowercase, like footnoteDefinition already was. The rule is defined in TxtAST Requirements: Extension nodes.

v15v16
Yamlyaml
Tomltoml
Jsonjson
FootnoteReferencefootnoteReference

If your rule or filter rule ignores "Yaml" by default, use "yaml" instead, or both names to support v15 and v16. Plugin authors who copied the mapping of @textlint/markdown-to-ast, such as for MDX, should rename these node types too.

Line endings are LF, CR, and CRLF​

textlint counts lines by LF, CR, and CRLF in every format.

  • Plain text: a lone CR is now a line ending, so the text is split into Paragraph, Break, and Paragraph, and loc of the following nodes changes #2197
  • Messages: the line and column of messages no longer treat U+2028 and U+2029 as line endings. rangeToLocation, locationToRange, positionToIndex, and indexToPosition of TextlintSourceCode follow the same definition. @textlint/kernel no longer depends on structured-source #2199

Plain text parser​

@textlint/text-to-ast was rewritten and keeps one Paragraph per line. The AST changes only for unusual texts:

  • Every line ending at the end of the text becomes a Break. a\n\n gives two Break nodes instead of one, and \n gives one instead of none
  • A BOM is no longer included in the first Str, so offsets are no longer one character too large
  • loc.end of Break is column 0 of the next line

#2198, #2194

@textlint/ast-tester checks position conventions​

test() throws and isTxtAST() returns false for an AST whose raw, range, and loc disagree with each other. textlint runs the tester only while testing a rule or plugin with textlint-tester, so linting documents is not affected. Plugin authors: the tests of a rule can start failing if your plugin produces such an AST. Count lines by LF, CR, and CRLF, and keep raw equal to the text sliced by range.

#2194, #2197

Removed deprecated type re-exports from @textlint/kernel​

The following types are no longer exported from @textlint/kernel. Import them from @textlint/types instead.

TextlintRuleReporter, TextlintRuleModule, TextlintRuleOptions, TextlintRuleSeverityLevel, TextlintFilterRuleReporter, TextlintFilterRuleOptions, TextlintPluginCreator, TextlintPluginOptions, TextlintPluginProcessor, TextlintPluginProcessorConstructor

// Before
import type { TextlintRuleModule } from "@textlint/kernel";
// After
import type { TextlintRuleModule } from "@textlint/types";

#2182

getSource option for formatters​

Formatters get the source text through a getSource(filePath) option instead of reading files by themselves. API users can pass in-memory text with loadFormatter({ formatterName, getSource }).

#2186

Other Changes​

  • The kernel calls rule handlers with less work per node: event emission, parent definition, and traversal of @textlint/ast-traverse avoid extra allocations. The order of visited nodes and the arguments of handlers do not change #2202
  • @textlint/ast-node-types: the children types include Definition, LinkReference, and ImageReference #2196
  • Removed unused dependencies #2184

Full Changelog​

See the release notes of v16.0.0 for all changes, and v15.8.0...v16.0.0 for all commits.

Thanks​

Thanks to all contributors and sponsors.