textlint/textlint

textlint/textlint

README

textlint


The pluggable linting tool for text and markdown. textlint is similar to ESLint, but it's for use with natural language.


GitHub Actions Build Status

Website


Online demo
Searchable documents
Release blog

Visit https://textlint.github.io/.

Features


No bundled rules.
To use a rule, install a textlint rule via npm.
npm install textlint-rule-xxx.
See collection of textlint rules

Markdown and plain text are supported by default. Support is available for HTML and other file formats via plugins.
Supports the use of custom formatters and formatter bundles formatter(reporter)

Quick Tour


For a quick tour of textlint, checkout our Getting Started guide :squirrel:

Installation


You can install the textlint command using npm:

  1. ``` sh
  2. $ npm install textlint --save-dev

  4. ```

Requirements:

Node.js 12+
npm 6+

If you're not sure what version of Node you're running, you can run node -v in your console to find out.

⚠️Warning:

If you have installed textlint globally you must install each reference rule globally as well.
If you have installed textlint locally you must install each rule locally as well.

We recommend installing textlint locally.

For Node.js beginners


If you've never used Node.js and npm, please see the following:

Installing Node.js and updating npm | npm Documentation

Usage


screenshot lint pretty-error

textlint has no default rules!!

You can run textlint with the --rule or --rulesdir flag to specify rules, or you can just use a .textlintrc config file.

  1. ``` shell
  2. # Install textlint's rule into local directory
  3. npm install --save-dev textlint-rule-no-todo
  4. ```

Use with textlint-rule-no-todo rule. (Allow to short textlint-rule-no-todo to no-todo )

  1. ``` shell
  2. npx textlint --rule no-todo README.md
  3. ```

📝We recommended using .textlintrc to specify rules instead of --rule or --rulesdir flags. Your .textlintrc is a great way to maintain your rules.

CLI


Run npx textlint -h for information on how to use the CLI.

  1. ``` sh
  2. $ textlint [options] file.md [file|dir|glob*]

  4. Options:
  5.   -h, --help                  Show help.
  6.   -c, --config path::String   Use configuration from this file or sharable config.
  7.   --ignore-path path::String  Specify path to a file containing patterns that describes files to ignore. - default: .textlintignore
  8.   --init                      Create the config file if not existed. - default: false
  9.   --fix                       Automatically fix problems
  10.   --dry-run                   Enable dry-run mode for --fix. Only show result, don't change the file.
  11.   --debug                     Outputs debugging information
  12.   --print-config              Print the config object to stdout
  13.   -v, --version               Outputs the version number.

  15. Using stdin:
  16.   --stdin                     Lint text provided on <STDIN>. - default: false
  17.   --stdin-filename String     Specify filename to process STDIN as

  19. Output:
  20.   -o, --output-file path::String  Enable report to be written to a file.
  21.   -f, --format String         Use a specific output format.

  23.                               Available formatter          : checkstyle, compact, jslint-xml, json, junit, pretty-error, stylish, table, tap, unix

  25.                               Available formatter for --fix: compats, diff, fixed-result, json, stylish - default: stylish
  26.   --no-color                  Disable color in piped output.
  27.   --quiet                     Report errors only. - default: false

  29. Specifying rules and plugins:
  30.   --no-textlintrc             Disable .textlintrc
  31.   --plugin [String]           Set plugin package name
  32.   --rule [String]             Set rule package name
  33.   --preset [String]           Set preset package name and load rules from preset package.
  34.   --rulesdir [path::String]   Use additional rules from this directory

  36. Caching:
  37.   --cache                     Only check changed files - default: false
  38.   --cache-location path::String  Path to the cache file or directory - default: .textlintcache

  40. Experimental:
  41.   --experimental              Enable experimental flag.Some feature use on experimental.
  42.   --rules-base-directory path::String  Set module base directory. textlint load modules(rules/presets/plugins) from the base directory.
  43.   --parallel                  Lint files in parallel
  44.   --max-concurrency Number    maxConcurrency for --parallel

  46. ```

When running texlint, you can target files to lint using the glob patterns. Make sure that you enclose any glob parameter you pass in quotes.

  1. ``` shell
  2. $ npx textlint "docs/**"
  3. ```

For more details, see CLI documentation.

Documentation: CLI

Example:

ℹ️* See examples/cli

.textlintrc


.textlintrc is config file that is loaded as JSON, YAML or JS via azu/rc-config-loader.

Running textlint with the following arguments

  1. ``` sh
  2. $ npx textlint --rule no-todo --rule very-nice-rule README.md

  4. ```

is equivalent to running textlint README.md in a directory with a .textlintrc containing the following json

  1. ``` json
  2. {
  3.   "rules": {
  4.     "no-todo": true,
  5.     "very-nice-rule": true
  6.   }
  7. }
  8. ```

You can also configure options for specific rules in your .textlintrc file.

  1. ``` json
  2. {
  3.   "rules": {
  4.     "no-todo": false, // disable
  5.     "very-nice-rule": {
  6.         "key": "value"
  7.     }
  8.   }
  9. }
  10. ```

For example here we pass the options ("key": "value") to very-nice-rule.

Options can be specified in your .textlintrc file as follows:

  1. ``` js
  2. {
  3.   // Allow to comment in JSON
  4.   "rules": {
  5.     "<rule-name>": true | false | object
  6.   }
  7. }
  8. ```

ℹ️for more details see

docs/configuring
examples/config-file

Plugin


A textlint plugin is a set of rules and rulesConfig or customize parser.

To enable plugin, put the "plugin-name" into .textlintrc.

  1. ``` js
  2. // `.textlintrc`
  3. {
  4.     "plugins": [
  5.         "plugin-name"
  6.     ],
  7.     // overwrite-plugins rules config
  8.     // /
  9.     "rules": {
  10.         "plugin-name/rule-name" : false
  11.     }
  12. }
  13. ```

ℹ️See docs/plugin.md

Supported file formats


textlint supports Markdown and plain text by default.

Install Processor Pluginand add new file format support.

For example, if you want to lint HTML, use textlint-plugin-html as a plugin.

  1. ``` sh
  2. npm install textlint-plugin-html --save-dev

  4. ```

Add "html" to .textlintrc

  1. ``` sh
  2. {
  3.     "plugins": [
  4.         "html"
  5.     ]
  6. }

  8. ```

Run textlint on .html files:

textlint index.html

Example: examples/html-plugin
Documentation: docs/plugin.md

Optional supported file types:

HTML: textlint-plugin-html
reStructuredText: textlint-plugin-rst
AsciiDoc/Asciidoctor: textlint-plugin-asciidoc-loose
Re:VIEW: textlint-plugin-review
Org-mode: textlint-plugin-org

See Processor Plugin List for details.

Rules list 💚


textlint has not built-in rules, but there are 100+ pluggable rules:

textlint-rule-no-todo
textlint-rule-max-number-of-lines
textlint-rule-common-misspellings
etc...

See A Collection of textlint rule · textlint/textlint Wiki for more details.

If you create a new rule, and add it to the wiki :)

Fixable


Some rules are fixable using the --fix command line flag.

  1. ``` shell
  2. $ npx textlint --fix README.md
  3. # As a possible, textlint fix the content.
  4. ```

fixable-error

Also, support dry run mode.

  1. ``` sh
  2. $ npx textlint --fix --dry-run --format diff README.md
  3. # show the difference between fixed content and original content.

  5. ```

You can copy and paste to your README.

  1. ``` gfm
  2. [![textlint fixable rule](https://img.shields.io/badge/textlint-fixable-green.svg?style=social)](https://textlint.github.io/)
  3. ```

Built-in formatters


Use the following formatters:

stylish (defaults)
compact
checkstyle
jslint-xml
junit
tap
table
pretty-error
json
unix

e.g. use pretty-error formatter:

  1. ``` sh
  2. $ npx textlint -f pretty-error file.md

  4. ```

More details in @textlint/linter-formatter.

Use as node module


You can use textlint as node module.

  1. ``` sh
  2. $ npm install textlint --save-dev

  4. ```

Minimal usage:

  1. ``` js
  2. import { TextLintEngine } from "textlint";
  3. const engine = new TextLintEngine({
  4.     rulePaths: ["path/to/rule-dir"]
  5. });
  6. engine.executeOnFiles(["README.md"]).then((results) => {
  7.     console.log(results[0].filePath); // => "README.md"
  8.     // messages are `TextLintMessage` array.
  9.     console.log(results[0].messages);
  10.     /*
  11.     [
  12.         {
  13.             id: "rule-name",
  14.             message:"lint message",
  15.             line: 1, // 1-based columns(TextLintMessage)
  16.             column:1 // 1-based columns(TextLintMessage)
  17.         }
  18.     ]
  19.      */
  20.     if (engine.isErrorResults(results)) {
  21.         const output = engine.formatResults(results);
  22.         console.log(output);
  23.     }
  24. });
  25. ```

Low level usage:

  1. ``` js
  2. import { textlint } from "textlint";
  3. textlint.setupRules({
  4.     // rule-key : rule function(see docs/rule.md)
  5.     "rule-key"(context) {
  6.         const exports = {};
  7.         exports[context.Syntax.Str] = function (node) {
  8.             context.report(node, new context.RuleError("error message"));
  9.         };
  10.         return exports;
  11.     }
  12. });
  13. textlint.lintMarkdown("# title").then((results) => {
  14.     console.log(results[0].filePath); // => "README.md"
  15.     console.log(results[0].messages); // => [{message:"lint message"}]
  16. });
  17. ```

More details on:

See docs/use-as-modules.md

Conclusion


textlint has four extensible points:

rule
rule is a rule for linting.

filter rule
filter rule is a rule for filtering result of errors.

rule-preset
rule-preset contains rules.

plugin
plugin contains a processor.

rule-preset-plugin

FAQ: How to create rules?


Please see docs/

docs/txtnode.md
What is TxtNode?

docs/rule.md
How to create rules?
Tutorial: creating no-todo rule.

docs/rule-advanced.md
Advanced tutorial for creating rule.

FAQ: How to suppress error by comments like <!-- textlint-disable -->?


You can use filter rule like textlint-filter-rule-comments.

Please see Ignoring Text · textlint for more details.

Integrations


For more details, see integrations document.

App


textlint-app
Standalone cross platform app. No need Node.js environment.

Build Systems


gulp plugin
gulp-textlint

Grunt plugin
grunt-textlint

Editors


Atom Editor
1000ch/linter-textlint

SublimeText
joeybaker/sublimelinter-textlint

Vim
vim-textlint
scrooloose/syntastic
See Markdown, Text and HTML of scrooloose/syntastic Wiki

VS Code
taichi/vscode-textlint

micro
hidaruma/micro-textlint-plugin

NetBeans
netbeans-textlint-plugin

Browser


Chrome Extension
Chrome: textlint-proofreader
io-monad/textlint-chrome-extension: textlint Chrome Extension

Other


Pronto : pronto-textlint
reviewdog : azu/textlint-reviewdog-example

Who's using textlint?


survivejs/webpack-book
hoodiehq/hoodie
asciidwango/js-primer
vuejs-jp/vuejs.org
cypress-io/cypress-documentation

Packages


This repository is a monorepo that we manage using Lerna. That means that we actually publish several packages to npm from the same codebase, including:

Core


These modules are parts of textlint.

| Package | Version | Description |
|:--- |:--- |:--- |
| textlint| | textlint command line tool itself |
| @textlint/kernel| | textlint main logic module. It is universal JavaScript. |
| @textlint/linter-formatter| | textlint output formatter |
| @textlint/fixer-formatter| | textlint output formatter for fixer |
| @textlint/textlint-plugin-markdown| | markdown support for textlint |
| @textlint/textlint-plugin-text| | plain text support for textlint |
| @textlint/ast-tester| | Compliance tests for textlint's AST |
| @textlint/markdown-to-ast| | markdown parser |
| @textlint/ast-traverse| | TxtNode traverse library |
| @textlint/text-to-ast| | plain text parser |

Rule/Plugin helper


These modules are useful for textlint rule/plugin author.

| Package | Version | Description |
|:--- |:--- |:--- |
| @textlint/ast-node-types| | textlint AST(Abstract Syntax Tree) type definition |
| textlint-tester| | textlint rule testing tools |
| textlint-scripts| | textlint rule npm run-scripts |
| create-textlint-rule| | create textlint rule with no build configuration |

Integrations


These modules are useful integration with textlint.

| Package | Version | Description |
|:--- |:--- |:--- |
| gulp-textlint| | gulp plugin for textlint |

Internal


These modules are internal usage in the monorepo.

| Package | Version | Description |
|:--- |:--- |:--- |
| @textlint/feature-flag| | feature flag manager |

Semantic Versioning Policy


textlint project follow Semantic Versioning. However, textlint is not different with most semver project.

Patch release (intended to not break your lint build)
A bug fix to the CLI or core (including formatters).
Improvements to documentation.
Non-user-facing changes such as refactoring.
Re-releasing after a failed release (i.e., publishing a release that doesn't work for anyone).

Minor release (might break your lint build)
A new option.
An existing rule is deprecated.
A new CLI capability is created.
New public API are added (new classes, new methods, new arguments to existing methods, etc.).
It might break type interface(.d.ts )

A new formatter is created.

Major release (break your lint build)
A new option to an existing rule that results in textlint reporting more errors by default.
An existing formatter is removed.
Part of the public API is removed or changed in an incompatible way.

Contributing


For bugs and feature requests, please create an issue.

Pull requests is always welcome.

For more details, see Contributing Guide.

License


MIT © azu

Copy some code from ESLint.

  1. ``` sh
  2. ESLint
  3. Copyright (c) 2013 Nicholas C. Zakas. All rights reserved.
  4. https://github.com/eslint/eslint/blob/master/LICENSE

  6. ```

Logos & Icons


Download from textlint/media.

Related Work


SCG: TextLint

Acknowledgements


Thanks to ESLint.

textlint website is powered by Netlify.