zhlint

A linting tool for Chinese text content.

How to install

You could easily install zhlint through npm or yarn:

# install through npm
npm install zhlint -g

# or through yarn
yarn global add zhlint

# or through pnpm
pnpm add zhlint -g

Usage

As CLI

# glob files, lint them, and print validation report,
# and exit with code `1` if there is any error found.
zhlint <file-pattern>

# glob files and fix their all possilbly found errors.
zhlint <file-pattern> --fix

# lint the file and output fixed content into another file
zhlint <input-file-path> --output=<output-file-path>

# print usage info
zhlint --help

The validation report might look like this:

Advanced usage

zhlint also supports rc and ignore config files for custom rules:

# .zhlintrc by default
zhlint --config <filepath>

# .zhlintignore by default
zhlint --ignore <filepath>

# current directory by default
zhlint --dir <path>

In the config file, you can write a JSON like:

{
  "preset": "default",
  "rules": {
    "adjustedFullWidthPunctuation": ""
  }
}

For more details, see supported rules.
In the ignore file, you can write some lines of ignored cases like:

( , )

For more details, see setup ignored cases.

As Node.js package

const { run, report } = require('zhlint')

const value = '自动在中文和English之间加入空格'
const options = { rules: { preset: 'default' } }
const output = run(value, options)

// print '自动在中文和 English 之间加入空格''
console.log(output.result)

// print validation report
report([output])

And the format of validation report is more like this:

1:6 - 此处中英文内容之间需要一个空格

自动在中文和English之间加入空格
　　　　　　^

1:13 - 此处中英文内容之间需要一个空格

自动在中文和English之间加入空格
       　　　　　　^
Invalid files:
- foo.md

Found 2 errors.

Advanced usage

zhlint also supports rc and ignore config files for custom rules:

const { readRc, runWithConfig } = require('zhlint')

const value = '自动在中文和English之间加入空格'

const dir = '...' // the target directory path
const configPath = '...' // the config file path
const ignorePath = '...' // the ignore file path

const config = readRc(dir, configPath, ignorePath)
const output = runWithConfig(value, config)

// ... further actions

As a standalone package

You could find a JavaScript file dist/zhlint.js as a standalone version. To use it, for example, you can directly add it into your browser as a <script> tag. Then there would be a global variable zhlint for you.

API

• run(str: string, options?: Options): Result: Lint a certain file.
  • parameters:
    • str: The text content you want to lint.
    • options: Some options to config.

    <li>
      returns: <ul dir="auto">
        <li>
          The result of a single piece of input string. It contains fixed text content as <code>value</code> and the infor of all <code>validations</code>.
        </li>
      </ul>
    </li>
  </ul>
  

  • report(results: Result[], logger?: Console): void: Print out the validation reports for each file.
    • parameters:
      • results: An array for all linted results.
      • logger: The logger instance, by default it’s console in Node.js/browser.
  • readRc: (dir: string, config: string, ignore: string, logger?: Console) => Config: Read config from rc file(s). For rc (run command).
  • runWithConfig(str: string, config: Config): Result: Lint a certain file with rc config. For rc (run command).

  Options

  Customize your own linting config and other advanced options.

  type Options = {
    rules?: RuleOptions
    hyperParse?: string[]
    ignoredCases?: IgnoredCase[]
    logger?: Console
  }

  • rules: customize the linting config. It could be undefined which means linting nothing. It could be { preset: 'default' } which just uses the default config. For more details of RuleOptions, please see supported rules
  • hyperParse: customize the hyper parser by their names. It could be undefined which means just use default ignored cases parser, Markdown parser and the Hexo tags parser.
  • ignoredCases: provide exception cases which you would like to skip.
    • IgnoredCase: { prefix?, textStart, textEnd?, suffix? }
      • Just follows a certain format inspired from W3C Scroll To Text Fragment Proposal.
  • logger: same to the parameter in report(...).

  RC Config

  • preset: string (optional)
  • rules: RuleOptions without the preset field. (optional)
  • hyperParsers: string[] (optional)
  • ignores: string[] and the priority is lower than .zhlintignore. (optional)

  Output

  type Result = {
    // the basic info and availability of the file
    file?: string
    disabled: boolean
  
    // the original content of the file
    origin: string
  
    // all the error messages
    validations: Validation[]
  }
  
  type Validation = {
    message: string
    index: number
    length: number
  }

  • Result
    • file: The file name. It’s an optional field which is only used in CLI.
    • origin: the original text content.
    • result: the finally fixed text content.
    • validations: All the validation information.
  • Validation
    • index: The index of the target token in the input string.
    • length: The length of the target token in the input string.
    • message: The description of this validation in natural language.

  Advanced usage

  Features

  Markdown syntax support

  We support lint your text content in Markdown syntax by default. For example:

  run('自动在_中文_和**English**之间加入空格', options)

  It will analyse the Markdown syntax first and extract the pure text content and do the lint job. After that the fixed pure text content could be replaced back to the raw Markdown string and returned as the output value in result.

  Hexo tags syntax support

  Specially, we support Hexo tags syntax just because when we use Hexo to build Vue.js website, the markdown source files more or less include special tags like that so got the unpredictable result.
  As a result, we additionally skip the Hexo-style tags by default. For example:

  run(
    '现在过滤器只能用在插入文本中 (`{% raw %}{{ }}{% endraw %}` tags)。',
    options
  )

  Setup ignored cases

  In some real cases we have special text contents not follow the rules by reason. So we could ues ignoredCases option to config that. For example we’d like to keep the spaces inside a pair of brackets, which is invalid by default. Then we could write one more line of HTML comment anywhere inside the file: