This document provides a high-level overview of the textlint repository, explaining its purpose as a pluggable natural language linting tool and describing the architecture of the monorepo. textlint is similar to ESLint but designed for prose rather than code, allowing users to lint and automatically fix text in various formats (Markdown, plain text, HTML, etc.) using configurable rules.
For detailed information about specific subsystems:
Sources: README.md1-10 packages/textlint/package.json2-4
textlint is a pluggable linting tool for natural language text that provides:
textlint-rule-no-todo)textlint --fix@textlint/kernel runs in any JavaScript environment (Node.js, browser)The repository is a monorepo containing 20+ packages managed by Lerna and pnpm, supporting Node.js 20+.
Sources: README.md10-36 package.json1-60
The following diagram maps textlint's logical architecture to actual code packages and entry points:
Sources: packages/textlint/package.json1-99 packages/@textlint/kernel/package.json1-62 packages/@textlint/config-loader/package.json1-62
The following diagram illustrates how text flows through the system, from input files to formatted output, showing the actual method calls and data structures:
Sources: packages/textlint/src/cli.ts packages/textlint/src/index.js1-50 packages/@textlint/kernel/src/textlint-kernel-interface.ts docs/use-as-modules.md1-150
The repository is organized as a monorepo managed by:
| Tool | Version | Purpose | Configuration |
|---|---|---|---|
| Lerna | 9.0.5 | Monorepo management, version bumping, publishing | lerna.json |
| pnpm | 10.30.3 | Package manager with workspace support | pnpm-lock.yaml1-10 |
| TypeScript | ~5.8.3 | Type checking and compilation | tsconfig.json project references |
All internal packages use workspace:* protocol for dependencies, ensuring tight integration:
@textlint/kernel
└─ workspace:* → @textlint/types
└─ workspace:* → @textlint/ast-node-types
└─ workspace:* → @textlint/ast-traverse
The monorepo contains these package categories:
Core Packages (in packages/):
textlint - CLI application packages/textlint/@textlint/kernel - Universal linting engine packages/@textlint/kernel/@textlint/types - TypeScript type definitions packages/@textlint/types/Parser Packages:
@textlint/markdown-to-ast - Markdown → TxtAST packages/@textlint/markdown-to-ast/@textlint/text-to-ast - Plain text → TxtAST packages/@textlint/text-to-ast/Plugin Packages:
@textlint/textlint-plugin-markdown packages/@textlint/textlint-plugin-markdown/@textlint/textlint-plugin-text packages/@textlint/textlint-plugin-text/Formatter Packages:
@textlint/linter-formatter - Lint result formatting packages/@textlint/linter-formatter/@textlint/fixer-formatter - Fix result formatting packages/@textlint/fixer-formatter/Developer Tools:
textlint-scripts - Build/test CLI for rule authors packages/textlint-scripts/textlint-tester - Rule testing framework packages/textlint-tester/Examples (in examples/): 12+ working examples demonstrating usage patterns
Integration Tests (in test/integration-test/): End-to-end validation
Sources: package.json1-61 pnpm-lock.yaml1-100 README.md511-562
textlint provides five extension points for customization:
Rules implement linting logic via the RuleContext API. Each rule exports a function that returns an object mapping AST node types to handler functions:
Key interfaces:
RuleContext - provides Syntax, report(), getSource(), fixer, locator docs/rule.md95-125RuleError - error reporting with optional padding for precise location docs/rule.md127-323TextlintMessage - output message structure docs/formatter.md42-62Plugins add support for new file formats via the Processor interface:
Key methods:
availableExtensions() - declares supported file extensions docs/plugin.md67-76preProcess() - converts text to TxtParentNode AST docs/plugin.md81-107postProcess() - packages messages into result docs/plugin.md171-177Filter rules suppress errors based on criteria using FilterRuleContext.shouldIgnore():
Presets bundle multiple rules with default configurations:
Formatters control output presentation. Built-in formatters include: stylish, json, github, checkstyle, junit.
Sources: docs/rule.md1-511 docs/plugin.md1-288 docs/filter-rule.md1-106 docs/rule-preset.md1-156 README.md410-423
textlint uses a standardized Abstract Syntax Tree (AST) called TxtAST for representing text:
| Package | Purpose | Key Exports |
|---|---|---|
@textlint/ast-node-types | AST node type constants | ASTNodeTypes.*, 50+ node types packages/@textlint/ast-node-types/src/ |
@textlint/types | TypeScript definitions | TxtNode, RuleContext, all interfaces packages/@textlint/types/src/ |
@textlint/ast-traverse | Tree traversal | traverse(), controller methods packages/@textlint/ast-traverse/src/ |
@textlint/ast-tester | AST validation | test(), isTxtAST() packages/@textlint/ast-tester/src/ |
Document - root container (TxtParentNode)Paragraph - paragraph block (TxtParentNode)Str - plain text (TxtTextNode with value)Header - heading with depth property (1-6)Link - hyperlink with url propertyCode - inline code (TxtTextNode)CodeBlock - code blockEmphasis, Strong - emphasis and boldAll nodes have:
type - node type string from ASTNodeTypesraw - original source textrange - [startIndex, endIndex] tuple (0-based)loc - { start: {line, column}, end: {line, column} } (line is 1-based, column is 0-based)parent - parent node reference (added at runtime)Sources: docs/txtnode.md1-461 packages/@textlint/ast-node-types/ packages/@textlint/types/
The textlint-scripts package provides standardized build/test workflows for rule authors:
Commands:
textlint-scripts init - generates README.md from template packages/textlint-scripts/scripts/init.js1-34textlint-scripts build - compiles TypeScript/ES2015+ code via Babel packages/textlint-scripts/scripts/build.js1-33textlint-scripts test - runs Mocha tests with Babel transpilation packages/textlint-scripts/scripts/test.js1-35Configuration:
tsconfig.json@babel/register for runtime transpilation packages/textlint-scripts/configs/babel-register.js1-16Testing framework for rules, integrating with Mocha:
Sources: packages/textlint-scripts/package.json1-81 packages/textlint-tester/package.json1-62 README.md534-543
textlint uses .textlintrc configuration files loaded via @textlint/config-loader:
Supported formats:
.textlintrc - JSON/YAML/JS (auto-detected).textlintrc.json - JSON with comment support.textlintrc.yml / .textlintrc.yaml - YAML.textlintrc.js - JavaScript modulepackage.json - textlint fieldConfiguration structure:
Rule severity levels:
"error" - exit with code 1 (default)"warning" - exit with code 0, yellow output"info" - exit with code 0, green output (v15.1.0+)Module resolution via @textlint/resolver:
textlint-rule-<name> or <name> or @scope/textlint-rule-<name>@textlint/module-interop for CommonJS/ESM compatibilitySources: docs/configuring.md1-298 packages/@textlint/config-loader/ packages/@textlint/resolver/
The repository uses GitHub Actions for continuous integration and automated releases:
CI Pipeline (.github/workflows/ci.yml):
npm test across all packages via LernaRelease Workflow:
create-release-pr.yml creates version bump PRlerna version to update all package versionsrelease.ymlrelease-canary.yml publishes @next versions for testingDocumentation:
website.yml - builds Docusaurus site, deploys to GitHub Pageswebsite-preview.yml - generates PR previews at /pr-preview/pr-{number}/Package publishing:
Sources: package.json4-31 README.md586-592 .github/workflows/
Refresh this wiki