pingcap / docs-cn

TiDB/TiKV/PD 中文文档
https://docs.pingcap.com/zh
Other
1.81k stars 1.21k forks source link

Add markdown style static-check #1463

Closed aylei closed 5 years ago

aylei commented 5 years ago

Feature Request

  1. Did you encounter a certain issue about the documentation? If yes, please describe the issue that relates to your feature request.

    No

  2. Please describe your suggestion or addition.

    I've received lots of markdown style suggestion in my PRs, it is great if we can add static-check for basic markdown style rules in favor of consistency and reduce the burden of reviewers.

  3. If convenient, please provide reference materials (Blog, Stack Overflow, etc).

    markdownlint is a great tool for markdown static-check, and it has a cli tool that can be easily integrated into CI. I've tested a previous PR on this, the result is satisfying:

$ markdownlint tidb-in-kubernetes/tkctl.md
tidb-in-kubernetes/tkctl.md: 6: MD025/single-title/single-h1 Multiple top level headings in the same document [Context: "# tkctl 使用说明"]
tidb-in-kubernetes/tkctl.md: 26: MD014/commands-show-output Dollar signs used before commands without showing output [Context: "$ git clone https://github.com..."]
tidb-in-kubernetes/tkctl.md: 37: MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
tidb-in-kubernetes/tkctl.md: 46: MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
tidb-in-kubernetes/tkctl.md: 58: MD014/commands-show-output Dollar signs used before commands without showing output [Context: "$ tkctl version"]
tidb-in-kubernetes/tkctl.md: 68: MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
tidb-in-kubernetes/tkctl.md: 180: MD014/commands-show-output Dollar signs used before commands without showing output [Context: "$ tkctl debug demo-cluster-tik..."]
tidb-in-kubernetes/tkctl.md: 180: MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
tidb-in-kubernetes/tkctl.md: 180: MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
tidb-in-kubernetes/tkctl.md: 199: MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
tidb-in-kubernetes/tkctl.md: 208: MD014/commands-show-output Dollar signs used before commands without showing output [Context: "$ tkctl debug demo-cluster-tik..."]
tidb-in-kubernetes/tkctl.md: 227: MD014/commands-show-output Dollar signs used before commands without showing output [Context: "$ tkctl ctop demo-cluster-tikv..."]
tidb-in-kubernetes/tkctl.md: 227: MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
tidb-in-kubernetes/tkctl.md: 238: MD014/commands-show-output Dollar signs used before commands without showing output [Context: "$ tkctl help debug"]
tidb-in-kubernetes/tkctl.md: 238: MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
tidb-in-kubernetes/tkctl.md: 247: MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
tidb-in-kubernetes/tkctl.md: 247: MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
tidb-in-kubernetes/tkctl.md: 278: MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
tidb-in-kubernetes/tkctl.md: 283: MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]

Note that the above example disables rule MD013 (line width) via config file:

$ cat .markdownlint.yaml
MD013: false

I am also wondering if we can extend this tool to add more rules that are dedicated to pingcap/docs and pingcap/docs-cn

lilin90 commented 5 years ago

@aylei We're very interested in your suggestion. And we'll appreciate it a lot if you can help to implement it. That would make the reviewing process much easier. ^_^