本项目是适用于中文技术文档写作的 textlint 规则预设方案,包含多种规则以检查文本中是否存在一些错误,其中多数规则附带修复功能,可供用户一键修复错误。
如果你有好的建议或疑问,欢迎发表 issue。
本项目需要:
- v12.20.0 及以上版本的 Node.js(如果使用 Node.js 运行)
- v5.0.0 及以上的 npm
- v12.0.0 以上的 textlint
目前,本预设方案包含以下的规则,其中标有 的为可以进行自动修复的规则。
如果你有其他规则的需求,欢迎发表 issue。
名称 | 介绍 | |
---|---|---|
textlint-rule-zh-correctly-ordered-pairs | 检测像引号、书名号这些需要成对按顺序使用的标点符号在文本中是否被正确使用 | |
textlint-rule-zh-double-zh-ellipsis | 检测文本中使用的省略号是否符合规范 | |
textlint-rule-zh-no-redundant-punctuation | 检测文本中是否出现了多余的标点符号 | |
textlint-rule-zh-no-redundant-space-around-token | 检测并修复文本中多余的空格 | |
textlint-rule-zh-no-space-around-zh-punct | 检测并修复文本中标点符号周围多余的空格 | |
textlint-rule-zh-no-space-between-num-and-unit-symbol | 检测并修复文本中数字和单位符号之间多余的空格 | |
textlint-rule-zh-space-around-inline-code | 检测并修复 Markdown 文本中行内代码周围缺失的空格 | |
textlint-rule-zh-space-between-zh-and-en-or-num | 检测并修复汉字与英文、数字之间缺失的空格 | |
textlint-rule-terminology | 检测并修复误用的英文术语 | |
textlint-rule-no-invalid-control-character | 检测并修复文本中出现的无效的控制字符 |
目前,textlint 仅支持 .txt
格式的纯文本和 .md
格式的 Markdown 文本,如果尝试将它用到 .html
文件中,可能出现难以预料的后果。
如果你在使用过程中对某个规则有疑问,请参考它对应的 README,packges 文件夹里包含所有规则的源码,其中也包含 README。 如果你觉得你遇到了误判,欢迎发表 issue。
textlint 提供了一套命令行工具,可供用户直接在命令行里使用本预设:
-
安装 textlint 和本预设:
npm install -g textlint textlint-rule-preset-zh-technical-writing
-
运行 textlint:
textlint --preset textlint-rule-preset-zh-technical-writing --fix <要lint的文件名>
-
你的文件此时会被 textlint 结合本预设进行 lint,其中出现的部分错误会被自动修复,但有些错误需要人工修复。请仔细查看控制台输出的内容。
textlint 命令行工具提供许多额外的选项,请使用 textlint --help
来查看。
WIP,等我几天。
本项目处于早期阶段,可能存在不少 Bug。如果你遇到了规则误判的问题,除了发表 issue 之外,可以临时通过以下方法让 textlint 忽略你的部分文本:
<!-- textlint-disable -->你要忽略的文本<!-- textlint-enable -->
若要参与本项目的开发,请执行以下步骤:
- 克隆本仓库,使用像
git clone
这样的命令。 - 如果你没有安装
yarn
,请执行npm install -g yarn
。 - 执行
yarn
。 - 执行
yarn init
。
在仓库根目录下运行 yarn test
。
本项目使用 babel 来转换源码中的 ES6 模块语法,以及嵌入 polyfill(基于 core-js)。
同时,本项目使用 lerna 管理,因此在本地测试时,packages
文件夹里的包之间的依赖,是通过在项目根目录下的 node_modules
文件夹里的软链接来实现的。
例如,textlint-rule-zh-space-around-inline-code
依赖的 textlint-test-util-zh
实际上是由 node_modules/textlint-test-util-zh
软链接指向 packages/textlint-test-util-zh
。
通过执行 yarn
,可以自动添加这样的软链接,而为了确保本地测试能够运行,并且你做的修改能够生效,在本地开发时推荐运行 yarn build:watch
来自动监视代码修改,实时编译。