plugin.md

id	title
plugin	Plugin

Each plugin is an npm module with a name in the format of textlint-plugin-<plugin-name>. For example, @textlint/textlint-plugin-markdown is a textlint plugin.

Processor

Plugin has a Processor that is required.

// index.js
export default {
    Processor: require("./YourProcessor")
};

Processor class defined pre/post process of the file and available file types.

textlint support .txt and .md by default. These are implemented as Processor plugin.

• @textlint/textlint-plugin-markdown
• @textlint/textlint-plugin-text
• textlint/textlint-plugin-html

Processor class example code:

// TextProcessor.js
import { parse } from "txt-to-ast";
export default class TextProcessor {
    constructor(options = {}) {
        this.options = options;
        // support "extension" option
        this.extensions = this.config.extensions ? this.config.extensions : [];
    }
    // available ".ext" list
    // user can add own custom extension as "extensions" option
    availableExtensions() {
        return [".txt", ".text"].concat(this.extensions);
    }
    // define pre/post process
    // in other words, parse and generate process
    processor(ext) {
        return {
            preProcess(text, filePath) {
                // parsed result is an AST object
                // AST is consist of TxtNode
                // https://github.com/textlint/textlint/blob/master/docs/txtnode.md
                return parse(text);
            },
            postProcess(messages, filePath) {
                return {
                    messages,
                    filePath: filePath ? filePath : "<text>"
                };
            }
        };
    }
}

Processor class should implement these method.

availableExtensions(): string[]

It should return supported extension name list.

Notes:

textlint@10<= support static availableExtensions(): string[]. The static method is deprecated in textlint@11. you should implement availableExtensions() method as instance method.

processor(ext)

processor() method should return an object that have preProcess and postProcess method.

preProcess(text, filePath): TxtParentNode | { text: string; ast: TxtParentNode; }

preProcess method should return TxtParentNode object or { text: string, ast: TxtParentNode } object. TxtParentNode object is an Abstract Syntax Tree (AST) of the text.

ℹ️ For more details about TxtParentNode, see TxtAST interface documents.

Target file(text format) -> AST(by your plugin) for Target file

If your plugin handle text format, you can just return a TxtParentNode object.

Target file(binary format) -> Intermediate text(by your plugin) -> AST(by your plugin) for Intermediate text

If your plugin handle intermediate text, you should return a { text: string, ast: TxtParentNode } object.

textlint can not handle binary format and your plugin should return intermediate text for your AST.

For more details, see textlint#649

postProcess(messages, filePath)

postProcess method should return { messages, filePath }. filePath argument may be undefined when text was input from stdin.

Plugin configuration

You can use Processor plugin in the same way a plugin.

{
    "plugins": [
        "<Processor Plugin>"
    ]
}

options

You can pass options to your plugin from .textlintrc.

{
    "plugins": {
        "pluginName": processorOption
    }
}

You can receive the processorOption via constructor arguments.

export default class YourProcessor {
    constructor(options) {
        this.options = options; // <= processorOption!
    }
    // ...
}

📝 Processor's option value is {} (empty object) by default. If not set plugin's option in .textlintrc, textlint pass {} as options.

export default class YourProcessor {
    constructor(options) {
        this.options = options; // {}
    }
    // ...
}

Publishing

If you want to publish your textlint plugin, see following documents.

Package name convention

textlint plugin package naming should have textlint-plugin- prefix.

• textlint-plugin-<name>
• @scope/textlint-plugin-<name>
  • textlint supports Scoped packages

Example: @textlint/textlint-plugin-markdown

textlint user use it by setting following:

{
    "plugins": {
        "@textlint/markdown": true
    }
}

Also, textlint user can set options to the plugin.

{
  "plugins": {
      "@textlint/markdown": {
        "extensions": [".custom-ext"]
      }
  }
}

Keywords

You should add textlintplugin to npm's keywords

{
  "name": "textlint-plugin-format-name",
  "keywords": [
    "textlintplugin"
  ]
}

Plugin Example

(limited) XML plugin

• azu/textlint-plugin-xml-example

For more plugins, See Processor Plugin List.

Built-in plugin

textlint has built-in plugins

• @textlint/textlint-plugin-text
• @textlint/textlint-plugin-markdown