Skip to content

Commit 84b33b2

Browse files
JinjiangJinjiang
committed
docs: update advanced usage
1 parent 5c35e3a commit 84b33b2

File tree

2 files changed

+152
-0
lines changed

2 files changed

+152
-0
lines changed

‎README.md

+72
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,42 @@ The validation report might look like this:
4040

4141
![](docs/screenshot-cli.png)
4242

43+
#### Advanced usage
44+
45+
zhlint also supports rc and ignore config files for custom rules:
46+
47+
```bash
48+
# .zhlintrc by default
49+
zhlint --config <filepath>
50+
51+
# .zhlintignore by default
52+
zhlint --ignore <filepath>
53+
54+
# current directory by default
55+
zhlint --dir <path>
56+
```
57+
58+
In the config file, you can write a JSON like:
59+
60+
```json
61+
{
62+
"preset": "default",
63+
"rules": {
64+
"adjustedFullWidthPunctuation": ""
65+
}
66+
}
67+
```
68+
69+
For more details, see [supported rules](#supported-rules).
70+
71+
In the ignore file, you can write some lines of ignored cases like:
72+
73+
```txt
74+
( , )
75+
```
76+
77+
For more details, see [setup ignored cases](#setup-ignored-cases).
78+
4379
### As Node.js package
4480

4581
```js
@@ -74,6 +110,25 @@ Invalid files:
74110
Found 2 errors.
75111
```
76112

113+
#### Advanced usage
114+
115+
zhlint also supports rc and ignore config files for custom rules:
116+
117+
```js
118+
const { readRc, runWithConfig } = require('zhlint')
119+
120+
const value = '自动在中文和English之间加入空格'
121+
122+
const dir = '...' // the target directory path
123+
const configPath = '...' // the config file path
124+
const ignorePath = '...' // the ignore file path
125+
126+
const config = readRc(dir, configPath, ignorePath)
127+
const output = runWithConfig(value, config)
128+
129+
// ... further actions
130+
```
131+
77132
### As a standalone package
78133

79134
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.
@@ -92,6 +147,8 @@ You could find a JavaScript file `dist/zhlint.js` as a standalone version. To us
92147
- parameters:
93148
- `results`: An array for all linted results.
94149
- `logger`: The logger instance, by default it's `console` in Node.js/browser.
150+
- `readRc: (dir: string, config: string, ignore: string, logger?: Console) => Config`: Read config from rc file(s). For rc (run command).
151+
- `runWithConfig(str: string, config: Config): Result`: Lint a certain file with rc config. For rc (run command).
95152

96153
### Options
97154

@@ -113,6 +170,13 @@ type Options = {
113170
- Just follows a certain format inspired from [W3C Scroll To Text Fragment Proposal](https://github.com/WICG/ScrollToTextFragment).
114171
- `logger`: same to the parameter in `report(...)`.
115172
173+
### RC Config
174+
175+
- `preset`: `string` (optional)
176+
- `rules`: `RuleOptions` without the `preset` field. (optional)
177+
- `hyperParsers`: `string[]` (optional)
178+
- `ignores`: `string[]` and the priority is lower than `.zhlintignore`. (optional)
179+
116180
### Output
117181
118182
```ts
@@ -145,6 +209,8 @@ type Validation = {
145209
- `length`: The length of the target token in the input string.
146210
- `message`: The description of this validation in natural language.
147211
212+
### Advanced usage
213+
148214
## Features
149215
150216
### Markdown syntax support
@@ -193,6 +259,12 @@ or just pass it through as an option:
193259
run(str, { ignoredCases: { textStart: '( ', textEnd: ' )' } })
194260
```
195261

262+
If you want to ignore the whole file, you can also add this HTML comment:
263+
264+
```md
265+
<!-- zhlint disabled -->
266+
```
267+
196268
## Supported preproccessors (hyper parsers)
197269

198270
- `ignore`: find all ignored pieces by the HTML comment `<!-- zhlint ignore: ... -->`

‎docs/index.md

+80
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,46 @@ The validation report might look like this:
4444

4545
![](./screenshot-cli.png)
4646

47+
#### Advanced usage
48+
49+
zhlint also supports rc and ignore config files for custom rules:
50+
51+
<details>
52+
53+
```bash
54+
# .zhlintrc by default
55+
zhlint --config <filepath>
56+
57+
# .zhlintignore by default
58+
zhlint --ignore <filepath>
59+
60+
# current directory by default
61+
zhlint --dir <path>
62+
```
63+
64+
In the config file, you can write a JSON like:
65+
66+
```json
67+
{
68+
"preset": "default",
69+
"rules": {
70+
"adjustedFullWidthPunctuation": ""
71+
}
72+
}
73+
```
74+
75+
For more details, see [supported rules](#supported-rules).
76+
77+
In the ignore file, you can write some lines of ignored cases like:
78+
79+
```txt
80+
( , )
81+
```
82+
83+
For more details, see [setup ignored cases](#setup-ignored-cases).
84+
85+
</details>
86+
4787
### As Node.js package
4888

4989
```js
@@ -78,6 +118,29 @@ Invalid files:
78118
Found 2 errors.
79119
```
80120

121+
#### Advanced usage
122+
123+
zhlint also supports rc and ignore config files for custom rules:
124+
125+
<details>
126+
127+
```js
128+
const { readRc, runWithConfig } = require('zhlint')
129+
130+
const value = '自动在中文和English之间加入空格'
131+
132+
const dir = '...' // the target directory path
133+
const configPath = '...' // the config file path
134+
const ignorePath = '...' // the ignore file path
135+
136+
const config = readRc(dir, configPath, ignorePath)
137+
const output = runWithConfig(value, config)
138+
139+
// ... further actions
140+
```
141+
142+
</details>
143+
81144
### As a standalone package
82145

83146
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.
@@ -96,6 +159,8 @@ You could find a JavaScript file `dist/zhlint.js` as a standalone version. To us
96159
- parameters:
97160
- `results`: An array for all linted results.
98161
- `logger`: The logger instance, by default it's `console` in Node.js/browser.
162+
- `readRc: (dir: string, config: string, ignore: string, logger?: Console) => Config`: Read config from rc file(s). For rc (run command).
163+
- `runWithConfig(str: string, config: Config): Result`: Lint a certain file with rc config. For rc (run command).
99164

100165
### Options
101166

@@ -117,6 +182,13 @@ type Options = {
117182
- Just follows a certain format inspired from [W3C Scroll To Text Fragment Proposal](https://github.com/WICG/ScrollToTextFragment).
118183
- `logger`: same to the parameter in `report(...)`.
119184
185+
### RC Config
186+
187+
- `preset`: `string` (optional)
188+
- `rules`: `RuleOptions` without the `preset` field. (optional)
189+
- `hyperParsers`: `string[]` (optional)
190+
- `ignores`: `string[]` and the priority is lower than `.zhlintignore`. (optional)
191+
120192
### Output
121193
122194
```ts
@@ -149,6 +221,8 @@ type Validation = {
149221
- `length`: The length of the target token in the input string.
150222
- `message`: The description of this validation in natural language.
151223
224+
### Advanced usage
225+
152226
## Features
153227
154228
### Markdown syntax support
@@ -197,6 +271,12 @@ or just pass it through as an option:
197271
run(str, { ignoredCases: { textStart: '( ', textEnd: ' )' } })
198272
```
199273

274+
If you want to ignore the whole file, you can also add this HTML comment:
275+
276+
```md
277+
<!-- zhlint disabled -->
278+
```
279+
200280
## Supported preproccessors (hyper parsers)
201281

202282
- `ignore`: find all ignored pieces by the HTML comment `<!-- zhlint ignore: ... -->`

0 commit comments

Comments
 (0)