textlint

The pluggable linting tool for text and markdown.
It is similar to ESLint, but textlint for natural language.

Online Demo

Visit https://textlint.github.io/ and type text!

Features

• No bundle rules.
• To use rule, Install textlint rule via npm.
  • npm install textlint-rule-xxx.
  • See collection of textlint rules
• Markdown and plain text are support by default. HTML and other formats are supported by plugins.
• Allow to use bundled formatter(reporter) and custom formatters

Quick Tour

Quick tour of textlint!

Read Getting Started :squirrel:

Installation

You can install textlint command using npm:

$ npm install textlint -g

Requirement:

• Node.js 4.0.0 >=
• npm 2.0.0 >=

Test: Run node -v in your console. The version should be higher than v4.0.0.

⚠️ Caution: Mixed location of installation.

• If you have installed textlint as --global(-g), must install each rule as --global.
• If you have installed textlint as --save-dev(-D), must install each rule as --save-dev.

Recommended way: Install textlint and rules as --save-dev per project.

For Node.js beginner

If you never use Node.js and npm(package manager for Node.js), please see following:

• Installing Node.js and updating npm | npm Documentation

Usage

textlint has no default rule!!

Use textlint with --rule or --rulesdir, .textlintrc config file.

# Install textlint's rule
npm install --global textlint-rule-no-todo

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

textlint --rule no-todo README.md

📝 We recommended to use .textlintrc insteadof --rule or --rulesdir. .textlintrc is suitable format for maintain rules.

CLI

See command help

$ textlint -h
textlint [options] file.md [file|dir|glob*]

Options:
  -h, --help                 Show help.
  -c, --config path::String  Use configuration from this file or sharable config.
  --init                     Create the config file if not existed. - default: false
  --fix                      Automatically fix problems
  --dry-run                  Enable dry-run mode for --fix. Only show result, don't change the file.
  --debug                    Outputs debugging information
  -v, --version              Outputs the version number.

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

Output:
  -o, --output-file path::String  Enable report to be written to a file.
  -f, --format String        Use a specific output format.
  --no-color                 Disable color in piped output.
  --quiet                    Report errors only. - default: false

Specifying rules and plugins:
  --plugin [String]          Set plugin package name
  --rule [path::String]      Set rule package name
  --preset [path::String]    Set preset package name and load rules from preset package.
  --rulesdir [path::String]  Set rules from this directory and set all default rules to off.

Caching:
  --cache                    Only check changed files - default: false
  --cache-location path::String  Path to the cache file or directory

Experimental:
  --experimental             Enable experimental flag.Some feature use on experimental.

Allow to use glob as a target.

Please note that have to quote your parameter as follows:

$ textlint "docs/**"

Example:

• ℹ️ See examples/cli

.textlintrc

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

$ textlint --rule no-todo --rule very-nice-rule README.md

is equal to create .textlintrc file

{
  "rules": {
    "no-todo": true,
    "very-nice-rule": true
  }
}

and run textlint command

$ textlint README.md
# Automatically load `.textlintrc` in current directory

.textlintrc can define rule's option.

{
  "rules": {
    "no-todo": false, // disable
    "very-nice-rule": {
        "key": "value"
    }
  }
}

Pass rule's options("key": "value") to very-nice-rule.

It mean that use the following format:

{
  // Allow to comment in JSON
  "rules": {
    "<rule-name>": true | false | object
  }
}

ℹ️ for more details

• docs/configuring
• examples/config-file

Plugin

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

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

// `.textlinrc`
{
    "plugins": [
        "plugin-name"
    ],
    // overwrite-plugins rules config
    // <plugin>/<rule>
    "rules": {
        "plugin-name/rule-name" : false
    }
}

ℹ️ See docs/plugin.md

Supported file formats

textlint support Markdown and plain text by default.

Install Processor Plugin and add new file format support.

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

npm install textlint-plugin-html

Add "html" to .textlintrc

{
    "plugins": [
        "html"
    ]
}

Run textlint on .html files:

textlint index.html

• Example : examples/html-plugin
• Document: 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

See Processor Plugin List for details.

Rule 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 new rule, and add it to the wiki :)

Fixable

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

$ textlint --fix README.md
# As a possible, textlint fix the content.

Also, support dry run mode.

$ textlint --fix --dry-run --formatter diff README.md
# show the difference between fixed content and original content.

You can copy and page to your README.

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

Built-in formatters

Use following formatter.

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

e.g.) use pretty-error formatter

$ textlint -f pretty-error file.md

More detail in textlint/textlint-formatter.

Use as node modules

You can use textlint as node modules.

$ npm install textlint --save-dev

Minimal usage:

import {TextLintEngine} from "textlint";
const engine = new TextLintEngine({
    rulePaths: ["path/to/rule-dir"]
});
engine.executeOnFiles(["README.md"]).then(results => {
    console.log(results[0].filePath);// => "README.md"
    // messages are `TextLintMessage` array.
    console.log(results[0].messages);
    /* 
    [
        {
            id: "rule-name",
            message:"lint message",
            line: 1, // 1-based columns(TextLintMessage)
            column:1 // 1-based columns(TextLintMessage)
        }
    ]
     */
    if (engine.isErrorResults(results)) {
        const output = engine.formatResults(results);
        console.log(output);
    }
});

Low level usage:

import {textlint} from "textlint";
textlint.setupRules({
    // rule-key : rule function(see docs/rule.md)
    "rule-key": function(context){
        const exports = {};
        exports[context.Syntax.Str] = function (node) {
            context.report(node, new context.RuleError("error message"));
        };
        return exports;
    }
});
textlint.lintMarkdown("# title").then(results => {
    console.log(results[0].filePath);// => "README.md"
    console.log(results[0].messages);// => [{message:"lint message"}]
});

More detail 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 rules and a processor.

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 docs/configuring.md for more details.

Integrations

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

Browser

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

Other

• Pronto: pronto-textlint

Who's using textlint?

• vuejs-jp/vuejs.org

The vuejs.org for japanese.

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

License

MIT and

lib/load-rules.js, util/traverse.js, cli.js and timing.js are:

ESLint
Copyright (c) 2013 Nicholas C. Zakas. All rights reserved.
https://github.com/eslint/eslint/blob/master/LICENSE

Logos & Icons

Download from textlint/media.

Related Work

SCG: TextLint is similar project.

SCG: TextLint's place is equal to my textlint(Fortuitously, project's name is the same too!).

via Natural Language Checking with Program Checking Tools

Acknowledgements

Thanks to ESLint.