The pluggable natural language linter for text and markdown.
JavaScript Other
Latest commit 2c1a8fb Jan 7, 2017 @azu azu committed on GitHub docs: use textlintrule

README.md

textlint

textlint logo

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

Travis CI Build Status AppVeyor Build status

Online Demo

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

Features

Quick Tour

Quick tour of textlint!

Read Getting Started :shipit:

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:

Usage

screenshot lint pretty-error

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:

.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

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

Optional supported file types:

See Processor Plugin List for details.

Rule list 💚

textlint has not built-in rules, but there are 100>= pluggable rules.

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

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

Fixable

textlint rule

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

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

fixable-error

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:

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.

rule-preset-plugin

FAQ: How to create rules?

Please see docs/

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

Editors

Browser

Other

Who's using textlint?

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!).

concept

via Natural Language Checking with Program Checking Tools

Acknowledgements

Thanks to ESLint.