zhlint

https://zhlint.jinjiang.dev
Admin
zhlint is a linting tool for Chinese text content that automatically formats and validates spacing,...
Tokens:3,153
Snippets:32
Trust Score:7.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install zhlint

Source: https://zhlint.jinjiang.dev/

Commands to install zhlint globally using npm, yarn, or pnpm.

```bash
# install through npm
npm install zhlint -g

# or through yarn
yarn global add zhlint

# or through pnpm
pnpm add zhlint -g
```

--------------------------------

### JSON Configuration File

Source: https://zhlint.jinjiang.dev/

Example structure for a .zhlintrc configuration file.

```json
{
  "preset": "default",
  "rules": {
    "adjustedFullwidthPunctuation": ""
  }
}
```

--------------------------------

### Case Ignore File Format

Source: https://zhlint.jinjiang.dev/

Example content for a case-ignore file using specific syntax.

```txt
( , )
```

--------------------------------

### Validation Report Output

Source: https://zhlint.jinjiang.dev/

Example of the validation report format generated by zhlint.

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

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

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

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

Found 2 errors.
```

--------------------------------

### runWithConfig(str: string, config: Config): Result

Source: https://zhlint.jinjiang.dev/

Lints content using a specific configuration object.

```APIDOC
## runWithConfig(str: string, config: Config): Result

### Description
Lint a certain content with rc config.
```

--------------------------------

### run(str: string, options?: Options): Result

Source: https://zhlint.jinjiang.dev/

Lints a specific string of text based on provided options.

```APIDOC
## run(str: string, options?: Options): Result

### Description
Lint a certain content and return the fixed text content along with validation information.

### Parameters
- **str** (string) - Required - The text content you want to lint.
- **options** (Options) - Optional - Configuration options for the linting process.
```

--------------------------------

### run(str, options)

Source: https://zhlint.jinjiang.dev/

The primary function to lint and format text content. It processes the input string based on the provided options and returns the fixed content.

```APIDOC
## run(str, options)

### Description
Lint and format the provided text content. It analyzes the input based on the specified rules and returns the processed result.

### Parameters
- **str** (string) - Required - The text content to be linted.
- **options** (object) - Optional - Configuration options for the linting process.

### Options
- **ignoredCases** (object) - Optional - Configuration to ignore specific text patterns. Example: `{ textStart: '( ', textEnd: ' )' }`.
- **preset** (string) - Optional - Custom preset, currently supports 'default'.
- **halfwidthPunctuation** (string) - Optional - Punctuations to convert into halfwidth.
- **fullwidthPunctuation** (string) - Optional - Punctuations to convert into fullwidth.
- **adjustedFullwidthPunctuation** (string) - Optional - Fullwidth punctuations to treat as half-fullWidthPunctuation.
- **unifiedPunctuation** (string|object) - Optional - Configuration for unifying traditional/simplified Chinese punctuations.
- **skipAbbrs** (string[]) - Optional - List of abbreviations to skip fullWidthPunctuation processing.
- **spaceBetweenHalfwidthContent** (boolean) - Optional - Whether to enforce one space between halfwidth content.
- **noSpaceBetweenFullwidthContent** (boolean) - Optional - Whether to enforce zero space between fullwidth content.
```

--------------------------------

### CLI Usage

Source: https://zhlint.jinjiang.dev/

Common CLI commands for linting, fixing, and outputting reports.

```bash
# 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
```

--------------------------------

### Advanced CLI Configuration

Source: https://zhlint.jinjiang.dev/

Commands for specifying custom configuration and ignore files.

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

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

# .zhlintcaseignore by default
zhlint --case-ignore <filepath>

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

--------------------------------

### Advanced Node.js API Usage

Source: https://zhlint.jinjiang.dev/

Using readRc and runWithConfig for advanced configuration management in Node.js.

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

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

const dir = '...' // the target directory path
const configPath = '...' // the config file path
const fileIgnorePath = '...' // the file-ignore file path
const caseIgnorePath = '...' // the case-ignore file path

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

// ... further actions
```

--------------------------------

### Define rule options

Source: https://zhlint.jinjiang.dev/

Configure linting rules including punctuation and spacing behavior.

```ts
type RuleOptions = {
  /* PRESET */

  // Custom preset, currently only support:
  // - `'default'`
  preset?: string

  /* PUNCTUATIONS */

  // Convert these punctuations into halfwidth.
  // default preset: `()`
  // e.g. `（文字）` -> `(文字)`
  halfwidthPunctuation?: string

  // Convert these punctuations into fullwidth.
  // default preset: `，。：；？！“”‘’`
  // e.g. `文字,文字.` -> `文字，文字。`
  fullwidthPunctuation?: string

  // Treat these fullwidth punctuations as half-fullWidthPunctuation
  // when processing the spaces issues around them.
  // Since something like quotations in morder Chinese fonts are
  // only rendered in halfwidth.
  // default preset: `“”‘’`
  adjustedFullwidthPunctuation?: string

  // Convert traditional Chinese punctuations into simplified ones or vice versa.
  // default preset: `simplified`
  // e.g. `「文字」` -> `“文字”`
  //
  // besides the above, we also unify some common punctuations below:
  //
  // // U+2047 DOUBLE QUESTION MARK, U+203C DOUBLE EXCLAMATION MARK
  // // U+2048 QUESTION EXCLAMATION MARK, U+2049 EXCLAMATION QUESTION MARK
  // '？？': ['⁇'],
  // '！！': ['‼'],
  // '？！': ['⁈'],
  // '！？': ['⁉'],
  //
  // // U+002F SOLIDUS, U+FF0F FULLWIDTH SOLIDUS
  // '/': ['/', '／'],
  //
  // // U+FF5E FULLWIDTH TILDE
  // '~': ['~', '～'],
  //
  // // U+2026 HORIZONTAL ELLIPSIS, U+22EF MIDLINE HORIZONTAL ELLIPSIS
  // '…': ['…', '⋯'],
  //
  // // U+25CF BLACK CIRCLE, U+2022 BULLET, U+00B7 MIDDLE DOT,
  // // U+2027 HYPHENATION POINT, U+30FB KATAKANA MIDDLE DOT
  // '·': ['●', '•', '·', '‧', '・'],
  //
  // advanced usage: you can also specify a more detailed map like:
  //
  // ```
  // {
  //   default: true, // follow all the default preset
  //   '「': ['“', '【'], // convert `“` or `【` into `「`
  //   '」': ['”', '】'], // convert `”` or `】` into `」`
  //  '…': true, // follow the default preset for this character
  //  '·': false, // not unify any of these characters
  // }
  // ```
  unifiedPunctuation?:
    | 'traditional'
    | 'simplified'
    | (Record<string, boolean | string[]> & { default: boolean })

  // Special case: skip `fullWidthPunctuation` for abbreviations.
  // default preset:
  // `['Mr.','Mrs.','Dr.','Jr.','Sr.','vs.','etc.','i.e.','e.g.','a.k.a']`
  skipAbbrs?: string[]

  /* SPACES AROUND LETTERS */

  // default preset: `true`
  // - `true`: one space
  // - `undefined`: do nothing
  // e.g. `foo  bar` -> `foo bar`
  spaceBetweenHalfwidthContent?: boolean

  // default preset: `true`
  // - `true`: zero space
  // - `undefined`: do nothing
  // e.g. `文 字` -> `文字`
  noSpaceBetweenFullwidthContent?: boolean
}
```

--------------------------------

### Node.js API Usage

Source: https://zhlint.jinjiang.dev/

Basic usage of the zhlint Node.js package to run linting and generate reports.

```js
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])
```

--------------------------------

### readRc(dir: string, config: string, fileIgnore: string, caseIgnore: string, logger?: Console): Config

Source: https://zhlint.jinjiang.dev/

Reads configuration from rc and ignore files.

```APIDOC
## readRc(dir: string, config: string, fileIgnore: string, caseIgnore: string, logger?: Console): Config

### Description
Read configuration from rc & ignore file(s).
```

--------------------------------

### Define linting options

Source: https://zhlint.jinjiang.dev/

Configuration object for customizing linting rules, parsers, and ignored cases.

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

--------------------------------

### Configure ignored cases

Source: https://zhlint.jinjiang.dev/

Define ignored cases using HTML comments or configuration options.

```md
<!-- the good case -->

text before (text inside) text after

<!-- the bad case -->

vm.$on( event, callback )

<!-- then we could write this down below to make it work -->
<!-- zhlint ignore: ( , ) -->
```

```js
run(str, { ignoredCases: { textStart: '( ', textEnd: ' )' } })
```

```md
<!-- zhlint disabled -->
```

--------------------------------

### report(results: Result[], logger?: Console): void

Source: https://zhlint.jinjiang.dev/

Prints validation reports for linted results.

```APIDOC
## report(results: Result[], logger?: Console): void

### Description
Print out the validation reports for each file.

### Parameters
- **results** (Result[]) - Required - An array of linted results.
- **logger** (Console) - Optional - The logger instance, defaults to console.
```

--------------------------------

### Define linting result structure

Source: https://zhlint.jinjiang.dev/

Data structures representing the linting output and individual validation errors.

```typescript
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
}
```

--------------------------------

### Lint Hexo tags

Source: https://zhlint.jinjiang.dev/

Lint text containing Hexo-style tags, which are skipped by default.

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

--------------------------------

### Lint Markdown text

Source: https://zhlint.jinjiang.dev/

Lint text content using Markdown syntax.

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