zhlint

https://github.com/zhlint-project/zhlint
Admin
zhlint is a linting and formatting tool for Chinese text content, helping to automatically format...
Tokens:7,510
Snippets:100
Trust Score:6.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install zhlint

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

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

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

### Define zhlint JSON Configuration

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Example structure for a .zhlintrc configuration file.

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

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

### Define zhlint Case Ignore File

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Example content for a case-ignore file.

```txt
( , )
```

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

### View zhlint Validation Report Format

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Example output format for a validation report.

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

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

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

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

Found 2 errors.
```

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

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

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Lints a provided string of text based on optional configuration settings.

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

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

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

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

### Use zhlint CLI

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

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

```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 --fix <file-pattern>[, ...]

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

# print usage info
zhlint --help
```

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

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

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Lints a string of text using a specific configuration object.

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

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

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

### CLI Usage

Source: https://github.com/zhlint-project/zhlint/blob/main/docs/index.md

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

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

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

### Configure zhlint CLI

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

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

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

### Use zhlint Advanced Node.js API

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Using runWithConfig to lint text with custom configuration files.

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

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

### case-math-exp formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles mathematical expressions and date formats.

```text
case-math-exp：1+1=2 1 + 1 = 2 1 + 2=3 2020/01/01 2020-01-01 vue-custom-element 100% a/b Chrome 53+ 中文
```

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

### RuleOptions

Source: https://github.com/zhlint-project/zhlint/blob/main/docs/index.md

The RuleOptions interface defines the configuration parameters for controlling how zhlint processes and formats text.

```APIDOC
## RuleOptions

### Description
Configuration object for defining linting rules for Chinese text processing.

### Parameters
- **preset** (string) - Optional - Custom preset, currently only 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 for fullWidthPunctuation.
- **spaceBetweenHalfwidthContent** (boolean) - Optional - Whether to add a space between halfwidth content.
- **noSpaceBetweenFullwidthContent** (boolean) - Optional - Whether to remove spaces between fullwidth content.
- **spaceBetweenMixedwidthContent** (boolean) - Optional - Whether to add a space between mixed-width content.
- **skipZhUnits** (string) - Optional - Chinese units to skip for mixed-width spacing.
- **noSpaceBeforePauseOrStop** (boolean) - Optional - Whether to remove space before pause or stop punctuations.
- **spaceAfterHalfwidthPauseOrStop** (boolean) - Optional - Whether to add space after halfwidth pause or stop punctuations.
- **noSpaceAfterFullwidthPauseOrStop** (boolean) - Optional - Whether to remove space after fullwidth pause or stop punctuations.
- **spaceOutsideHalfwidthQuotation** (boolean) - Optional - Whether to add space outside halfwidth quotations.
- **noSpaceOutsideFullwidthQuotation** (boolean) - Optional - Whether to remove space outside fullwidth quotations.
```

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

### Use zhlint as Node.js Package

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Basic usage of the zhlint Node.js API to run linting and report results.

```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://github.com/zhlint-project/zhlint/blob/main/README.md

Reads configuration settings from rc and ignore files.

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

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

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

### mark-type formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles type markers and links.

```text
`TODO: should be mark-type：a__[b](x)__c __[d](y)__ e 中文`
mark-type：a__[b](x)__c__[ d ](y)__e 中文
```

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

### case-raw formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles raw code blocks.

```text
case-raw：`AC`/`DC` 中文
```

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

### case-datetime formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles date and time string formats.

```text
case-datetime：2020/01/02 01:20:30 中文 2020 年1月1日0天0号0时0分00秒
```

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

### mark-raw formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles raw text markers within strings.

```text
mark-raw：a `b` c `d`e`f` g`h`i 中文
```

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

### Define a rule factory

Source: https://github.com/zhlint-project/zhlint/blob/main/docs/design.md

Rules are created by providing a function that accepts options and returns a Handler.

```ts
function (options: Options) => Handler
```

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

### Define Linting Options

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

The Options type defines the configuration for linting rules, hyper-parsers, ignored cases, and logging.

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

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

### Disable zhlint for a file

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Add an HTML comment to disable zhlint for the entire file.

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

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

### case-linebreak formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles multiline text formatting.

```text
case-linebreak：
this is  
a  
multiline  
text 中文
```

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

### case-html-entity formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles HTML entities within text.

```text
case-html-entity：中文&lt; &amp; &gt;中文
```

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

### Configure Content Spacing

Source: https://github.com/zhlint-project/zhlint/blob/main/docs/design.md

Define spacing rules for mixed-width content and specific punctuation types.

```typescript
spaceBetweenHalfwidthContent: true | undefined = true
```

```typescript
noSpaceBetweenFullwidthContent: true | undefined = true
```

```typescript
spaceBetweenMixedwidthContent: true | false | undefined = true
```

```typescript
noSpaceBeforePauseOrStop: true | undefined = true
```

```typescript
spaceAfterHalfwidthPauseOrStop: true | undefined = true
```

```typescript
noSpaceAfterFullwidthPauseOrStop: true | undefined = true
```

```typescript
noSpaceInsideQuotation: true | undefined = true
```

```typescript
spaceOutsideHalfwidthQuotation: true | false | undefined = true
```

```typescript
noSpaceOutsideFullwidthQuotation: true | undefined = true
```

```typescript
noSpaceInsideBracket: true | undefined = true
```

```typescript
spaceOutsideHalfwidthBracket: true | false | undefined = true
```

```typescript
noSpaceOutsideFullwidthBracket: true | undefined = true
```

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

### Configure Markdown Wrapper Spacing

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Controls spacing inside markdown or HTML wrappers.

```typescript
noSpaceInsideHyperMark?: boolean
```

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

### Configure ignored cases via options

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Pass ignored cases directly through the options object in the run function.

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

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

### Configure Bracket Spacing

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Controls spacing rules for halfwidth and fullwidth brackets.

```typescript
spaceOutsideHalfwidthBracket?: boolean
```

```typescript
noSpaceOutsideFullwidthBracket?: boolean
```

```typescript
noSpaceInsideBracket?: boolean
```

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

### Miscellaneous formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles miscellaneous text patterns.

```text
3 minite(s) left 中文

😉 &nbsp;中文
```

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

### case-abbr formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles abbreviations in mixed language text.

```text
case-abbr：Pure JavaScript (a.k.a. Vanilla) 中文
```

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

### space-brackets formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Adjusts spacing around brackets.

```text
space-brackets：(x)a(b)c (d )e( f) g ( h ) i（j）k （l） m __( a )__ b( __c__ )d(e) 中文
```

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

### Configure Punctuation Widths

Source: https://github.com/zhlint-project/zhlint/blob/main/docs/design.md

Define the characters treated as halfwidth or fullwidth punctuation.

```typescript
halfwidthPunctuation: string? = `()[]{}`
```

```typescript
fullwidthPunctuation: string? = `，。：；？！“”‘’`
```

```typescript
adjustedFullwidthPunctuation: string? = `“”‘’`
```

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

### Handle Hexo tags

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Skip Hexo-style tags during the linting process to prevent unpredictable results.

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

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

### Define RuleOptions Interface

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

The RuleOptions type defines the configuration schema for zhlint, covering punctuation handling, spacing rules, and character unification.

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

  // default preset: `true`
  // - `true`: one space
  // - `false`: zero space
  // - `undefined`: do nothing
  // e.g. `文字 foo文字` -> `文字 foo 文字` (`true`)
  // e.g. `文字foo 文字` -> `文字foo文字` (`false`)
  spaceBetweenMixedwidthContent?: boolean

  // Special case: skip `spaceBetweenMixedWidthContent`
  // for numbers x Chinese units.
  // default preset: `年月日天号时分秒`
  skipZhUnits?: string

  /* SPACES AROUND PUNCTUATIONS */

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

  // default preset: `true`
  // - `true`: one space
  // - `false`: zero space
  // - `undefined`: do nothing
  // e.g. `文字,文字` -> `文字, 文字` (`true`)
  // e.g. `文字, 文字` -> `文字,文字` (`false`)
  spaceAfterHalfwidthPauseOrStop?: boolean

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

  /* SPACES AROUND QUOTATIONS */

  // default preset: `true`
  // - `true`: one space
  // - `false`: zero space
  // - `undefined`: do nothing
  // e.g. `文字 "文字"文字` -> `文字 "文字" 文字` (`true`)
  // e.g. `文字"文字" 文字` -> `文字"文字"文字` (`false`)
  spaceOutsideHalfwidthQuotation?: boolean

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

```json
{
  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
}
```

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

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

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Prints validation reports for a collection of 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 all linted results.
- **logger** (Console) - Optional - The logger instance, defaults to console.
```

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

### Ignoring cases via HTML comments

Source: https://github.com/zhlint-project/zhlint/blob/main/docs/index.md

Use HTML comments within the file to ignore specific patterns or disable linting for the entire file.

```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: ( , ) -->
```

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

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

### Configure Trimming and Filtering

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Controls whitespace trimming and processing of western sentences.

```typescript
trimSpace?: boolean
```

```typescript
skipPureWestern?: boolean
```

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

### case-ellipsis formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles ellipsis punctuation.

```text
case-ellipsis：中文...中文...a...b... 中文 ... 中文 ... a ... b ...
```

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

### case-backslash formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles escaped backslashes in text.

```text
`TODO: should be case-backslash：a \# b 中文\# __中文__ \# 中文 __\#__ __中文__\#中文__\#__`
case-backslash：a \# b 中文\# __中文__ \# 中文 __\#__ __中文__\#中文__\#__
```

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

### unify-punctuation formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Standardizes punctuation marks in Chinese text.

```text
unify-punctuation：中文,中文 （中文） 中文'中文'中文"中文"中文 （中文）（中文）中文 （中文）。
```

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

### space-punctuation formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Adjusts spacing around punctuation marks.

```text
space-punctuation：中文 。 中文(中文)中文。中文 . 中文（中文）中文.
```

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

### case-traditional formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Handles traditional Chinese quotation marks.

```text
case-traditional：a「b『c』d」e 中文
```

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

### space-quotations formatting

Source: https://github.com/zhlint-project/zhlint/blob/main/test/example-units.md

Adjusts spacing around quotation marks.

```text
space-quotations: a " hello world " b 中文
```

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

### Configure Quotation Spacing

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Controls spacing inside quotation marks.

```typescript
noSpaceInsideQuotation?: boolean
```

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

### Configure Code Block Spacing

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Controls spacing around inline code blocks.

```typescript
spaceOutsideCode?: boolean
```

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

### Ignore specific text patterns

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Use HTML comments to ignore specific text patterns within a Markdown file.

```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: ( , ) -->
```

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

### Define a rule handler

Source: https://github.com/zhlint-project/zhlint/blob/main/docs/design.md

The Handler type defines the signature for functions that process individual tokens during rule traversal.

```ts
export type Handler = (token, index, group) => void
```

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

### Define Validation Result and Target Types

Source: https://github.com/zhlint-project/zhlint/blob/main/docs/design.md

Defines the structure for validation results and the specific targets within a token where errors can occur.

```ts
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 = {
  // the type and content of message
  name: string
  message: string

  // position of the token
  index: number
  length: number

  // which part of the token the error comes from
  target: ValidationTarget
}

enum ValidationTarget {
  // the main content
  VALUE
  // the space after the content
  SPACE_AFTER

  // for quotations, the left/right quotation
  START_VALUE
  END_VALUE
  // for quotations, space after the left quotation
  INNER_SPACE_BEFORE
}
```

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

### Define Result and Validation Structures

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

The Result type represents the outcome of a linting operation, containing the original content and a list of validation errors.

```ts
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 Markdown text

Source: https://github.com/zhlint-project/zhlint/blob/main/README.md

Lint text content formatted in Markdown by extracting pure text and re-inserting fixed content.

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