textlint v13.0.0
We just publish textlint v13.0.0, which is a major release upgrade of textlint.
textlint v13 support ESM rules/plugins native.
We have rewritten CLI and textlint package.
However, it is not a breaking change for most textlint CLI users.
Almost CLI behaviors are the same as textlint v12.
Summary
For textlint user
You can upgrade textlint via following commands:
npm install textlint@13 --save-dev
# or
yarn install textlint@13 --dev
textlint 13.0.0 requires Node.js 16+. If you use Node.js 14, you need to upgrade Node.js to 16+.
For textlint rule creator
You can write own rule as ESM module.
textlint v13.0.0 can load ESM rules native. So you need to transpile your rule to CommonJS.
textlint CLI load ESM rules and lint files!
:warning: However, textlint editor plugin may not support ESM rules yet. You need to wait for editor plugin author migrate to textlint new APIs.
For textlint module user
If you use textlint as node module, you should use new APIs.
textlint package provides new APIs from v12.3.0
We have introduced new API like createLinter for supporting Async APIs.
v13 continue to support current TextlintCore, TextLintEngine and TextFixEngine for backward compatible.
However, These API will be retired in the future.
New createLinter and loadTextlintrc supports ESM rules/plugins.
textlint modules user should use these instead of TextlintCore, TextLintEngine and TextFixEngine.
ℹ️ Timeline:
- textlint v12.3.0 support old APIs(deprecated) and new APIs
- use old APIs as default
- textlint v13.0.0 support old APIs(deprecated) and new APIs
- use new APIs as default - CURRENT
- textlint v14.0.0 drop to support old APIs
| API | Description | Behavior | Target Platform | v13+ |
|---|---|---|---|---|
| cli | Command LIne Interface | Async | Node.js | ✅ (Use createLinter and loadTextlintrc internally) |
| textlint | TextLintCore alias | Async | Node.js/CommonJS | ❌ Deprecated |
| TextLintCore | Old API. It is Procedural API. Lint Only Single File. Recommended to use @texltint/kernel module instead of It. | Async | Node.js/CommonJS | ❌ Deprecated |
| TextLintEngine | Lint Engine API. It load .textlintrc automaticaly | ◉ Loading is Sync ◉ Linting is Async | Node.js/CommonJS | ❌ Deprecated |
| TextFixEngine | Fix Engine API. It load .textlintrc automaticaly | ◉ Loading is Sync ◉ Fixing is Async | Node.js/CommonJS | ❌ Deprecated |
| createLinter/loadTextlintrc | Support Async APIs. | ◉ Loading is Async ◉ Linting/Fixing is Async | Node.js/CommonJS and ESM | ✅ Recommended |
New APIs
textlint v12.3.0 introduce new APIs.
textlint will drop support old APIs(textlint, TextLintEngine, TextFixEngine, and TextLintCore) in the future.
📝 Old APIs can not support ECMAScript modules, new APIs support ECMAScript modules.
createLinter: create linter instancelintFiles(files): Promise<TextlintResult[]>: lint files and return linter messageslintText(text, filePath): Promise<TextlintResult>lint text with virtual filePath and return linter messagesfixFiles(files): Promise<TextlintFixResult[]>lint text and return fixer messagesfixText(text, filePath): Promise<TextlintFixResult>lint text with virtual filePath and return fixer messagesfixFilesandfixTextdoes not modify files
loadTextlintrc: load.textlintrcconfig file and return a descriptor objectloadLinerFormatterandloadFixerFormatter: load formatter
Examples
Lint files and output to console.
import { createLinter, loadTextlintrc, loadLinterFormatter } from "textlint";
// descriptor is a structure object for linter
// It includes rules, plugins, and options
const descriptor = await loadTextlintrc();
const linter = createLinter({
descriptor
});
const results = await linter.lintFiles(["*.md"]);
// textlint has two types formatter sets for linter and fixer
const formatter = await loadLinterFormatter({ formatterName: "stylish" })
const output = formatter.format(results);
console.log(output);
For more details, please read next document.
If you have any questions, please ask us via GitHub Discussion.
ChangeLog
🔥 Breaking Changes
- Require Node.js 16+
textlint --initoutput.textlintrc.json- Previously,
textlint --initoutput.textlintrc
- Previously,
- Improve
@textlint/ast-node-typestypes- Now, All node types are defined!
- It changes the existing node type and it is a breaking change
- If you want to know TxtAST, please read TxtAST Interface
- Use New-CLI instead of Old-CLI
- textlint has introduced New-CLI and New-APIs in v12.3.0
- New-CLI uses new APIs:
createLinter/loadTextlintrc/loadLinterFormatter/loadFixerFormatter( If you want to know new APIs, please read Use as Node Modules) - It means that textlint support rules/plugins that are written by ESM 🎉
- Remove Old-CLI
Difference between Old-CLI and New-CLI
- New CLI support ESM rules/plugins
- New CLI must require
--stdin-filenamewith--stdin--stdin-filenamemay be optional in Old-CLI
- Correct exit status
Exit Status on new CLI
0: No Error
- Not found lint error
- --fix: found errors but fix all errors, so exit with 0
- --output-file: Found lint error but --output-file is specified
- --dryRun: Found lint error but --dryRun is specified
1: Lint Error
- found lint error
- --fix: found errors and could not fix all errors, so exit with 1
2: Fatal Error
- Crash textlint process
- Fail to load config/rule/plugin etc...
🆕 Features
Add individual Node type and Add Table/TableRow/TableCell node #1008
- Define all node types in
@textlint/ast-node-types - Add Table/TableRow/TableCell node to
@textlint/ast-node-types
These types are defined in @textlint/ast-node-types.
| Type name | Node type | Description |
|---|---|---|
| ASTNodeTypes.Document | TxtDocumentNode(TxtParentNode) | Root Node |
| ASTNodeTypes.DocumentExit | TxtDocumentNode(TxtParentNode) | |
| ASTNodeTypes.Paragraph | TxtParagraphNode(TxtParentNode) | Paragraph Node |
| ASTNodeTypes.ParagraphExit | TxtParagraphNode(TxtParentNode) | |
| ASTNodeTypes.BlockQuote | TxtBlockQuoteNode(TxtParentNode) | > Block Quote Node |
| ASTNodeTypes.BlockQuoteExit | TxtBlockQuoteNode(TxtParentNode) | |
| ASTNodeTypes.List | TxtListNode(TxtParentNode) | List Node |
| ASTNodeTypes.ListExit | TxtListNode(TxtParentNode) | |
| ASTNodeTypes.ListItem | TxtListItemNode(TxtParentNode) | List (each) item Node |
| ASTNodeTypes.ListItemExit | TxtListItemNode(TxtParentNode) | |
| ASTNodeTypes.Header | TxtHeaderNode(TxtParentNode) | # Header Node |
| ASTNodeTypes.HeaderExit | TxtHeaderNode(TxtParentNode) | |
| ASTNodeTypes.CodeBlock | TxtCodeBlockNode(TxtParentNode) | Code Block Node |
| ASTNodeTypes.CodeBlockExit | TxtCodeBlockNode(TxtParentNode) | |
| ASTNodeTypes.HtmlBlock | TxtHtmlBlockNode(TxtParentNode) | HTML Block Node |
| ASTNodeTypes.HtmlBlockExit | TxtHtmlBlockNode(TxtParentNode) | |
| ASTNodeTypes.Link | TxtLinkNode(TxtParentNode) | Link Node |
| ASTNodeTypes.LinkExit | TxtLinkNode(TxtParentNode) | |
| ASTNodeTypes.Delete | TxtDeleteNode(TxtParentNode) | Delete Node(~Str~) |
| ASTNodeTypes.DeleteExit | TxtDeleteNode(TxtParentNode) | |
| ASTNodeTypes.Emphasis | TxtEmphasisNode(TxtParentNode) | Emphasis(*Str*) |
| ASTNodeTypes.EmphasisExit | TxtEmphasisNode(TxtParentNode) | |
| ASTNodeTypes.Strong | TxtStrongNode(TxtParentNode) | Strong Node(**Str**) |
| ASTNodeTypes.StrongExit | TxtStrongNode(TxtParentNode) | |
| ASTNodeTypes.Break | TxtBreakNode | Hard Break Node(Str<space><space>) |
| ASTNodeTypes.BreakExit | TxtBreakNode | |
| ASTNodeTypes.Image | TxtImageNode | Image Node |
| ASTNodeTypes.ImageExit | TxtImageNode | |
| ASTNodeTypes.HorizontalRule | TxtHorizontalRuleNode | Horizontal Node(---) |
| ASTNodeTypes.HorizontalRuleExit | TxtHorizontalRuleNode | |
| ASTNodeTypes.Comment | TxtCommentNode | Comment Node |
| ASTNodeTypes.CommentExit | TxtCommentNode | |
| ASTNodeTypes.Str | TxtStrNode | Str Node |
| ASTNodeTypes.StrExit | TxtStrNode | |
| ASTNodeTypes.Code | TxtCodeNode | Inline Code Node |
| ASTNodeTypes.CodeExit | TxtCodeNode | |
| ASTNodeTypes.Html | TxtHtmlNode | Inline HTML Node |
| ASTNodeTypes.HtmlExit | TxtHtmlNode | |
| ASTNodeTypes.Table | TxtTableNode | Table node. textlint 13+ |
| ASTNodeTypes.TableExit | TxtTableNode | |
| ASTNodeTypes.TableRow | TxtTableRowNode | Table row node. textlint 13+ |
| ASTNodeTypes.TableRowExit | TxtTableRowNode | |
| ASTNodeTypes.TableCell | TxtTableCellNode | Table cell node. textlint 13+ |
| ASTNodeTypes.TableCellExit | TxtTableCellNode |
Some nodes have additional properties.
For example, TxtHeaderNode has level property.
export interface TxtHeaderNode extends TxtParentNode {
type: "Header";
depth: 1 | 2 | 3 | 4 | 5 | 6;
children: PhrasingContent[];
}
For more details, see @textlint/ast-node-types.
Full Changelog
Thanks for Support!
Many people support us, Thanks!
If you're interested in GitHub Sponsor, please check @azu on GitHub Sponsors!
