Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ci: check markdown grammar issues; 让CI自动检查markdown语法错误 #622

Closed
seeflood opened this issue Jun 4, 2022 · 4 comments · Fixed by #665
Closed

ci: check markdown grammar issues; 让CI自动检查markdown语法错误 #622

seeflood opened this issue Jun 4, 2022 · 4 comments · Fixed by #665
Assignees
Labels
good first issue Good for newcomers help wanted Extra attention is needed kind/ci kind/enhancement New feature or request priority/medium

Comments

@seeflood
Copy link
Member

seeflood commented Jun 4, 2022

What would you like to be added:
We can add some tools in github workflow to check grammar issues in our markdown files.
For example, the issue #433 should be found by CI automatically:

image

Why is this needed:
#433

@seeflood seeflood added kind/enhancement New feature or request good first issue Good for newcomers help wanted Extra attention is needed area/ci labels Jun 4, 2022
@seeflood seeflood mentioned this issue Jun 4, 2022
25 tasks
@seeflood seeflood changed the title ci: check markdown grammar issues ci: check markdown grammar issues; 让CI自动检查markdown语法错误 Jun 14, 2022
@leemos-xx
Copy link
Member

这个任务可以分配给我吗,我尝试一下

@seeflood
Copy link
Member Author

seeflood commented Jun 18, 2022

@leemos-xx Cool. Thanks!
I don't know how to implement it . We need to search and check if there are any existing solutions in the community

@seeflood
Copy link
Member Author

seeflood commented Jun 22, 2022

conversation in wechat group:

你好,这个问题我验证了一下,#433的问题是由于MD031 - Fenced code blocks should be surrounded by blank lines 规则不满足导致的,通过markdownlint是可以检查出该问题。然后关于哪些规则需要设置哪些不需要的问题,可以参看下这个文档来决定 https://docs.qq.com/sheet/DRGpJb1Ntc3hYVmh0 ,其中:
1、扫描的目录为layotto项目的docs目录;
2、错误数量是docs目录中的md不满足对应规则的报错的总数;
3、建议修复为Y,是根据设定该条规则的原因(Rationale:https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)初步判断的,如果可能会影响到部分编辑器的渲染,那这里我填的是建议修复;
4、整体错误数量还是蛮多的,需要决定下哪些可以先略过,或者逐步慢慢修复;

@seeflood
Copy link
Member Author

seeflood commented Jun 22, 2022

@leemos-xx 我想了下, 我们把策略定成这样呢: 只添加会导致 docsify 渲染异常的规则。
因为:

  1. 规则越少越好。规则越多,贡献者体验越差,因为每次提PR 都要花时间修 linter报错,修的多了大家会不开心,比如 让 CI 中的报错信息更直观 #646
  2. 我看了下规则,很多规则是说“如果你把 markdown 写成xxx样,那么不同的 markdown 编辑器渲染出来的效果不一样,所以不要这样做”。但其实我们只关心 docsify 渲染出来是什么样,不需要考虑“如果别的 markdown渲染器来渲染,会导致异常”。所以这类规则其实“并不会导致 docsify 渲染异常”,我们可以忽略

所以具体来说:

  • 我们添加 MD031 - Fenced code blocks should be surrounded by blank lines 这条会导致渲染异常的规则
  • 其他规则可以看下“是不是会导致 docsify 渲染异常”,如果会导致异常,那就添加(比如我看 MD037MD038 好像也会导致渲染问题) ; 如果不会,那其他规则先不加、这次只加“已知的、会导致渲染异常的规则” (比如 MD031, 037, 038,其他的我没细看) 就够了;等以后遇到其他渲染异常的case了,我们再针对性的加规则

这样如何?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue Good for newcomers help wanted Extra attention is needed kind/ci kind/enhancement New feature or request priority/medium
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants