textlint v16.0.0
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
Yamltoyaml. If your configuration lists"Yaml", such as intextlint-filter-rule-node-types, change it to"yaml". Otherwise front matter is checked as prose. - The output of some formatters changes slightly.
tableno longer throws on a tab in a message, andpretty-errorno longer printsundefinedfor an empty file. - New options.
--cache-strategy contentdetects changed files by content,--stdinworks with thepretty-erroranddiffformatters, and the Markdown plugin'scjkFriendlyEmphasisrecognizes 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-markdownand@textlint/textlint-plugin-textare ESM-only. Code that loads them directly withrequire()gets the module namespace, so userequire(...).defaultorimport.@textlint/markdown-to-astis 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 hiddenpositionproperty is removed.- Node types that are not in
@textlint/ast-node-typesare lowercase. Front matter and footnote references are not part of CommonMark or GFM, soYaml,Toml,Json, andFootnoteReferencebecomeyaml,toml,json, andfootnoteReference. 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
Paragraphper line. Every line ending at the end of the text becomes aBreak, and a BOM is no longer included in the firstStr(Plain text parsing Requirements). @textlint/ast-testerchecks thatraw,range, andlocagree. 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
getSourceoption. API users can pass in-memory text toloadFormatter().
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+
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:
| Documents | Before | v16 |
|---|---|---|
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:
| Project | Before | v16 |
|---|---|---|
| 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.
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"]
}
}
}
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 errortable: escape sequences in a message or a rule id are removed in the table cells. Without color, the output is the same as beforepretty-error: a message in an empty file no longer printsundefined- Column widths of some emoji follow newer Unicode data
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.
--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"
--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.
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.
Bug Fixes
TIMING=1reports each rule's own time instead of including other rules' time #2189- A relative
--rules-base-directoryis resolved from the current directory #2190 - The
githubformatter 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-typesare lowercase - Lines end with LF, CR, or CRLF in every format
raw,range, andlocof a node agree with each other, and@textlint/ast-testerchecks it
The breaking changes in this section come from these rules.
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";
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 locof the text after a task list checkbox and a line ending now matches itsrange- 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.
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.
| v15 | v16 |
|---|---|
Yaml | yaml |
Toml | toml |
Json | json |
FootnoteReference | footnoteReference |
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, andParagraph, andlocof 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, andindexToPositionofTextlintSourceCodefollow the same definition.@textlint/kernelno longer depends onstructured-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\ngives twoBreaknodes instead of one, and\ngives one instead of none - A BOM is no longer included in the first
Str, so offsets are no longer one character too large loc.endofBreakis column 0 of the next line
@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.
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";
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 }).
Other Changes
- The kernel calls rule handlers with less work per node: event emission,
parentdefinition, and traversal of@textlint/ast-traverseavoid extra allocations. The order of visited nodes and the arguments of handlers do not change #2202 @textlint/ast-node-types: the children types includeDefinition,LinkReference, andImageReference#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.
