Giter Club home page Giter Club logo

lint-md's Introduction

Lint Markdown 2.0

⚠️ 提示:你现在看到的是 2.0 版本,如果要查看 1.x 版本请切换到 1.x 分支。

Lint Markdown 是检查中文 Markdown 编写格式的工具,让你的文档更加优雅规范。

npm npm

新版特点

重构文本修复算法,fix 能力性能提升上百倍。

底层 Markdown 解析库 remark 迁移至最新版。

支持多线程 lint & fix。

体验更好的命令行输出提示。

项目架构完全重构,代码质量大幅提升,更方便 contribute 😄。

快速开始

我们提供了两种使用的方式,命令行和 Node.js API,前者适合大部分用户使用(推荐),后者适合更加定制化的 Lint 需求。

使用命令行(CLI)

安装依赖

npm install -g @lint-md/cli

命令示例

# 校验当前目录下的 test.md 文件
lint-md test.md

# 校验当前目录下的 test.md 文件,并修复之
lint-md test.md --fix

# 校验 examples 目录下所有的 Markdown 文件,并修复之
lint-md examples/**/* --fix

# 校验 examples 目录下所有的 Markdown 文件,指定 config.json 为配置文件(配置文件语法见下文)
lint-md examples/**/* --config=config.json

# 校验 examples 目录下所有的 Markdown 文件,仅存在 warning 时程序正常退出(warning 不会阻断 CI)
lint-md examples/**/* --suppress-warnings

# 校验 examples 目录下所有的 Markdown 文件,并开启多线程模式(线程数 === CPU 核心数)
lint-md examples/**/* --threads

# 校验 examples 目录下所有的 Markdown 文件,并开启多线程模式(线程数 === 8)
lint-md examples/**/* --threads=8

配置文件

默认情况下重新会读取根目录下的 .lintmdrc JSON 文件(如果有的话),下面是一个案例,表示将 no-empty-code 这条规则的等级设置为 warning,同时为 no-long-code 这条规则配置了自定义的选项:

{
  "rules":{
    "no-empty-code": 1,
    "no-long-code": [2, {
      "length": 100,
      "exclude": ["dot"]
    }]
  }
}

其中 key 为对应规则的名称,value 是一个数字或者对象。

如果是一个数字,那么表示规则的等级:

  • 0:忽略(off),不检查该规则
  • 1:警告(warning),仅出现警告,程序正常退出,不会阻断 CI
  • 2:错误(error),出现错误,程序异常退出,会阻断 CI

如果是一个数组,那么数组的第一项为数字,表示该规则的等级;第二个为规则的配置参数。

API 一览

Options:
  -v, --version                  output the version number(查看当前版本)
  -c, --config [configure-file]  use the configure file, default .lintmdrc(使用配置文件,默认为 .lintmdrc)
  -f, --fix                      fix the errors automatically(开启修复模式)
  -d, --dev                      open dev mode(开启开发者模式)
  -t, --threads [thread-count]   The number of threads. The default is based on the number of available CPUs.(执行 Lint / Fix 的线程数,默认为 CPU 核心数)
  -s, --suppress-warnings        suppress all warnings, that means warnings will not block CI(抑制所有警告,这意味着警告不会阻止 CI)
  -h, --help                     display help for command(查看帮助)

使用 Node.js API

TODO

规则概述

检查规则来源于 chinese-document-style-guide.

规则 详细描述 解决办法 可自动修复
space-around-alphabet 中文与英文之间需要增加空格 对应提示的位置增加空格
space-around-number 中文与数字之间需要增加空格 对应提示的位置增加空格
no-empty-code-lang 代码语言不能为空 在代码块语法上增加语言
no-empty-url 链接和图片地址不能为空 填写完整的 url,或者不使用链接和图片语法
no-empty-list list 内容不能为空 删除空的 list 或者补充内容
no-empty-code 代码块内容不能为空 删除空的代码块,或者填充代码内容
no-empty-inline-code 行内代码块内容不能为空 删除空的行内代码块,或者填充代码内容
no-empty-blockquote 引用块内容不能为空 删除空的引用块,或者填充内容
no-special-characters 文本中不能有特殊字符 可能是复制出来的特殊字符,删除特殊字符即可
use-standard-ellipsis 使用标准规范的省略号 使用标准规范的省略号‘……’ / ‘...’
no-fullwidth-number 不能用全角数字 注意输入法切换为半角输入
no-space-in-link 链接前后不能有空格 删除链接内容的前后空格
no-multiple-space-blockquote 引用块头部和内容间只能有一个空格 删除多余的空格
correct-title-trailing-punctuation 标题末尾只能使用合适的标点符号(允许问号、叹号、省略号) 删除标题最后不合法的标点符号
no-space-in-inline-code 行内代码内容前后不能有空格 删除行内代码中的前后空格
no-long-code 代码块不能有过长的代码(代码长度可配置,见下文) 对展示代码做格式上的修改 x

可配置的规则

no-long-code 接受两个可配置参数:

  • length: 每行代码接受的最大长度,数字,默认值为 100
  • exclude: 可以配置部分代码类型不做长度检查,字符串数组,默认值为 []

贡献代码

目前仅仅检查了比较通用的类型,欢迎 Pull Request,在 rules 中增加自己的规则,注意:

  • 规则主要针对于中文 Markdown 的编写规范
  • 规则名称对应和插件文件名保持一致
  • 先提 issue 进行讨论
  • 开发 rule 时可以使用 AST 工具 来辅助开发

License

MIT@hustcc.

lint-md's People

Contributors

dufu1991 avatar fivezh avatar genius-pig avatar hustcc avatar laysent avatar mengsixing avatar muyunyun avatar muzhou233 avatar wi1dcard avatar yeshiqing avatar yuzhanglong avatar ziqiangwang avatar zyszys avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

lint-md's Issues

附上LICENSE文件

package.json里说明是MIT LICENSE,但在repo上没找到对应的文件或者嵌在哪个文件里

请附上LICENSE文件,方便用户使用你的作品。

各个规则实现 --fix 逻辑

提交 ef8d3e5 中增加 --fix 的机制。

已经实现一个规则的 fix 逻辑(参考:src/fix-rules/no-empty-blockquote.js 文件)

需要实现,剩余各个规则的 fix 逻辑,要求:

  • 文件名和规则名保持一致
  • 规则的单测覆盖 100%
  • 每一个规则一个 commit,ref 到这个 issue

关于 excludeFiles 的问题

目录结构如下,典型 Hexo 目录:

source
├── _posts
│   ├── ...... more files
│   ├── jootu-copywriting-style-guide.md
│   └── ...... more files

我需要忽略 jootu-copywriting-style-guide.md 文件,于是配置 lint-md.json

{
  "excludeFiles": ["jootu-copywriting-style-guide.md"],
  // ...
}

执行命令:

lint-md source/_posts/* --config lint-md.json

但并没有忽略该文件,同时,我也尝试了以下的配置:

{
  "excludeFiles": ["**/jootu-copywriting-style-guide.md"],
  // ...
}

请问正确的使用方法是?谢谢!

feat: 要求行末必须有两个空格

一些 Markdown 解释器需要在行末添加两格空格才能实现换行,我也没有遇到过需要在markdown文件中换行而又不期望输出文本换行的情况。
是否可以增加一条可选的规则要求行末必须有两个空格

配置文件不存在时没有报错信息

复现步骤:

bash-3.2$ ls -l
total 16
-rw-r--r--  1 jootu  staff  29  1 27 12:38 config.json
-rw-r--r--  1 jootu  staff   7  1 27 12:46 test.md
bash-3.2$ lint-md . --config non-existent.json
Lint total 1 files, 0 warnings 0 errors

预期行为:报错并中止。

实际行为:按照没有指定 --config 的行为继续执行 Lint 过程。

关于打包新 Docker 镜像

遇到一问题,报错如下:

internal/modules/cjs/loader.js:236
      throw err;
      ^

Error: Cannot find module '/usr/local/lint-md/node_modules/ast-plugin/lib/index.js'. Please verify that the package.json has a valid "main" entry
    at tryPackage (internal/modules/cjs/loader.js:228:19)
    at Function.Module._findPath (internal/modules/cjs/loader.js:365:18)
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:612:27)
    at Function.Module._load (internal/modules/cjs/loader.js:527:27)
    at Module.require (internal/modules/cjs/loader.js:683:19)
    at require (internal/modules/cjs/helpers.js:16:16)
    at Object.<anonymous> (/usr/local/lint-md/packages/lint-md/lib/lint.js:14:18)
    at Module._compile (internal/modules/cjs/loader.js:776:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:787:10)
    at Module.load (internal/modules/cjs/loader.js:643:32) {
  code: 'MODULE_NOT_FOUND',
  path: '/usr/local/lint-md/node_modules/ast-plugin/package.json',
  requestPath: 'ast-plugin'
}

基本复现步骤:

cd lint-md
yarn install
cd packages/lint-md
yarn run build
cd ../lint-md-cli
bin/index.js

环境:

/usr/local/lint-md/packages/lint-md # yarn -v
1.16.0
/usr/local/lint-md/packages/lint-md # node -v
v12.6.0

no-fullwidth-number

  1. 数字不能使用:0123456789
  2. 比如出现 345,则提示一次,提示错误信息中携带错误的数字(参考 no-special-characters)

提示文字 Full width number exist: '345'

bug or question

Can anybody explain why the tool is formatting the following line, and which rule it's triggering?

image

I don't think it makes sense.

关于 CLI 标准输出的问题

在自己博客的 CI 流程上尝试集成,规则十分好用,但 CLI 存在一个问题:

在执行 lint-md 时,由于输出是不断「刷新」的,所以导致无法对标准输出使用管道。例如:

lint-md foo.md | grep `bar`

同样,把输出重定向到文件时,格式非常难看:

lint-md foo.md > result.log

最重要的影响是,在 Travis 日志上看到的输出是这样的:

脚本如下:

file_list=$(ls | grep -vE "jootu-copywriting-style-guide.md")
echo $file_list

lint-md $file_list --config "$dir/lint-md.json"

输出如下:

image

非常莫名其妙的只有第一行:total 0 file(s)

最早我怀疑是由于 $file_list 不正常导致,最后发现实际上已经 lint 了,只不过仅仅展示了第一次输出的内容,后面退格重新输出的都没有显示出来。

原因暂时未知,对这一块的具体实现不熟,Composer 或 NPM 的输出虽然也有退格、刷新,但日志正常。

增加规则

中文文案排版指北 这里提到的几个规则感觉可以考虑添加到规则中。

  • 数字与单位之间无需增加空格
  • 全角标点与其他字符之间不加空格
  • 不重复使用标点符号
  • 专有名词使用正确的大小写
  • 不要使用不地道的缩写

标题末尾符号判断有误

标题中符号判断有误:

首先要弄清楚的是,标题末尾能不能用问号。

黄伯荣、廖序东主编的《现代汉语》对标点符号的用法作了如下的说明:

"现在通行的标点符号有十四种,分为点号和标号两大类。句号、问号、感叹号、逗号、顿号、分号、冒号属于点号,引号、括号、破折号、省略号、书名号、着重号、间隔号属于标号。
"点号主要是表示语言中种种停顿的。标号主要是标明词语或句子的性质和作用的。
"也就是说,由于文章标题末尾是不需要停顿的,因此不能用逗号、句号等点号;但表明句子性质和作用的标号是可以用的,常用的如省略号。
"而问号和感叹号两种点号也兼属标号:就它表示问句、感叹句末了的停顿而言,是点号;就它表示疑问、感叹的性质而言,是标号。"

(同上)据此可知,标题末尾是可以用问号、省略号、叹号的。

Screen Shot 2021-02-02 at 10 56 38 AM

[bug] lint-md src/**/* 并没有识别到全部的文件

举例:

image

对于上图的目录结构,src/**/* 理应该识别到 src/user-guide/01-快速开始/02-添加条目.md,但他并没有,只有src/**/**/*才识别到这一级目录

northword@Yoga-Northword MINGW64 /d/Code/Zotero/zotero-document-zh (main)
$ lint-md src/**/**/*  -d
dev -- version: 2.0.0, Thu Jul 20 2023 16:17:53 GMT+0800 (香港标准时间)
Group 耗时: 159  Group 长度: 4  字符串长度: 32512
Group 耗时: 26  Group 长度: 2  字符串长度: 5005
Group 耗时: 11  Group 长度: 15  字符串长度: 1181
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0

⌛️Done in 406ms.

northword@Yoga-Northword MINGW64 /d/Code/Zotero/zotero-document-zh (main)
$ lint-md src/**/* -d
dev -- version: 2.0.0, Thu Jul 20 2023 16:18:02 GMT+0800 (香港标准时间)
Group 耗时: 50  Group 长度: 2  字符串长度: 3941
Group 耗时: 3  Group 长度: 3  字符串长度: 25
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0
Group 耗时: 0  Group 长度: 0  字符串长度: 0

⌛️Done in 238ms.

yuque/lint-md:cli无法找到

docker run --rm -it -v$(pwd)/docs yuque/lint-md:cli /docs/README.md # 也可直接带其它参数

1、目前https://hub.docker.com/r/yuque/lint-md,并不存在cli的tag,导致拉取失败

docker: Error response from daemon: manifest for yuque/lint-md:cli not found.

2、改用docker run --rm -it -v$(pwd)/docs yuque/lint-md /docs/README.md,提示lint-md命令无法找到

docker: Error response from daemon: OCI runtime create failed: container_linux.go:344: starting container process caused "exec: \"lint-md\": executable file not found in $PATH": unknown.

3、Circle CI平台之前的CI均失败
图片

README.md 中大小写不规范问题

请留意英文大小写问题:

  • ci 都应该是 CI,固定的缩写格式
  • List 都应该是 list
  • markdown 都应该是 Markdown
  • vscode 一般应该是 VS Code
  • webhook 都应该是 WebHook

no-space-in-links

  • wrong
[ a link ](http://www.example.com/)
  • right
[a link](http://www.example.com/)

半角标点如何检测

很多人写文档的时候,都喜欢在中文之间夹杂半角标点,如:

这是一个很好的东西,我很喜欢.

这种可以有 Lint 规则支持吗?

完善规则单测覆盖

帮助将 rules 目录单测覆盖达到 100%。

  • | space-round-alphabet
  • | space-round-number
  • | no-empty-code-lang
  • | no-empty-url
  • | no-empty-list
  • | no-empty-code
  • | no-empty-blockquote
  • | no-special-characters
  • | use-standard-ellipsis
  • | no-fullwidth-number
  • | no-space-in-emphasis
  • | no-space-in-link
  • | no-multiple-space-blockquote
  • | no-trailing-punctuation

Translate to En

Guys, please translate readmy.md to english for other can use lint-md.
Thanks.

关于docker的问题

docker run --rm -it yuque/lint-md lint-md README.md Document.md # 也可直接带其它参数

这条命令能够直接利用 docker 容器验证宿主机的 markdown 文件吗?

其中 README.md Document.md 是指什么?

no-trailing-punctuation

  • wrong
# This is a header.
  • right
# This is a header

对应标点:.,;:!?。,;:!?

支持 --fix 参数

要是能像 eslint 那样支持 --fix 参数就更好啦,能够自动修正一些简单的 lint errors(比如自动在中文与英文数字之间增加空格)。

refactor: 迁移至 remark 10.x

  • 当前项目的 markdown 解析依赖 remark 版本较低,部分 md 文本解析有误,例如这个pr:lint-md/cli#4
  • 在更新依赖之后,发现有大量的单侧无法通过,故需要重构,可能改动较大

TODO LIST

规则 详细描述 解决办法 迁移情况
space-round-alphabet 中文与英文之间需要增加空格 对应提示的位置增加空格 🆗
space-round-number 中文与数字之间需要增加空格 对应提示的位置增加空格 🆗
no-empty-code-lang 代码语言不能为空 在代码块语法上增加语言 🆗
no-empty-delete delete 块内容不能为空 删除空的 delete 文本块  不考虑,在最新的 remark 中对于空的 delete 块会被视为纯文本
no-empty-url 链接和图片地址不能为空 填写完整的 url,或者不使用链接和图片语法 🆗
no-empty-list List 内容不能为空 List 语法中,填写内容 🆗
no-empty-code 代码块内容不能为空 删除空的代码块,或者填充代码内容 🆗
no-empty-inlinecode 行内代码块内容不能为空 删除空的代码块,或者填充代码内容 🆗
no-empty-blockquote blockquote 内容不能为空 删除空的 blockquote,或者填充内容 🆗
no-special-characters 文本中不能有特殊字符 可能是复制出来的特殊字符,删除特殊字符即可 🆗
use-standard-ellipsis 使用标准规范的省略号 使用标准规范的省略号‘……’ / ‘...’ 🆗
no-fullwidth-number 不能用全角数字 注意输入法切换为半角输入 🆗
no-space-in-emphasis emphasis 内容前后不能有空格 删除 emphasis 内容中的前后空格即可   不考虑,emphasis 周围有空格会被解析成字符串
no-space-in-link link 内容前后不能有空格 删除 link 内容中的前后空格即可 🆗
no-multiple-space-blockquote blockquote 语法不能包含有多个空格 删除 blockquote 内容中多余的空格 🆗
no-trailing-punctuation 标题不能以标点符号结尾 删除标题最后的标点符号 🆗
no-space-in-inlinecode 行内代码内容,前后不能有空格 删除行内代码中的前后空格 🆗
no-long-code 代码块不能有过长的代码 对展示代码做格式上的修改 🆗

bug in use-standard-ellipsis

貌似出了个小问题,第一个 error 没报错。。
screen shot 2018-11-29 at 8 50 07 pm

是不是这里应该改成 3 ?

27   const re = /\.{4,}/g; // 使用正则匹配

API 调用方式

仅提供 cli 工具,在很多场景无法使用。开放 API 的调用方式,不仅仅是作为 cli 的底层,也可以用于其他场景:

  • 三方 markdown 应用继承格式校验功能
  • 浏览器 markdown 编辑器集成语法校验
  • ……

提供 API 如下:

import { lint, fix } from 'lint-md';

const errors = lint(markdown, rulesConfig = {}); // lint markdown 字符串

const newMarkdown = fix(markdown, rulesConfig = {}); // 修复 markdown 字符串,返回修复后的 markdown

error 防护返回格式改成:

type: string,
text: string,
level: string,
start: {
  line: number,
  column: number,
},
end: {
  line: number,
  column: number,
}

no-space-in-emphasis

  • wrong
Here is some ** bold ** text.

Here is some * italic * text.
  • right
Here is some **bold** text.

Here is some *italic* text.

use-standard-ellipsis

标准规范的省略号为:……

错误示例:

  • ...
  • ......

case by case 处理即可。

Windows 环境下的通配符错误

lint-md ./*

在 Windows 系统中使用该命令会报错

internal/fs/utils.js:220
    throw err;
    ^

Error: ENOENT: no such file or directory, stat 'C:\[DirectoryPath]\*.md'

而同样的命令在 Linux 系统或 Windows Subsystem for Linux 中都会正常展开通配符。
这是我的配置错误还是一个 BUG ?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.