Docs formatting checks using markdown linting - Runner

Rasam Hossainrequested to merge
rasamhossain/markdown-edge-cases into main

What does this MR do?

We're currently experiencing a fair number of Translation Merge Requests having markdown issues specially with incorrect bolding and italics assignment. In this MR, we are creating a few markdown checks to warn the reviewers of these issues. Due to possible false positives, in our initial iteration, we'll only have them as warnings and will not fail the pipelines.

We currently have all of these changes merged to GitLab. Currently expanding this to GitLab Operator.

Here's all the variation of issues that has been found based on testing different Translation MRs on this issue: Edge cases with Emphasis in Markdown ->

Bold Checks - Asterisk Style (**)

  1. Spaces inside bold markers ** text **
  2. Space after opening **
  3. Space before closing **

Bold Checks - Underscore Style (__)

  1. Spaces inside bold markers __ text __
  2. Space after opening __
  3. Space before closing __

Italic Checks - Asterisk Style (*)

  1. Spaces inside italic markers * text *

Italic Checks - Underscore Style (_)

  1. Spaces inside italic markers _ text _

ja-JP specific validations

  1. Fullwidth asterisks ＊ (should be *)

Others

  1. Four or more consecutive asterisks ****

Complete Reference Table

# Bash Script Check Tool Rule ID Severity Iteration
1 Bold ** with parens **text(unit)** Bash or Standard N/A Error/Warning Future MR
2 Spacing in ** (both sides) Standard MD037 Warning Covered by Current MR
3 Space after opening ** Standard MD037 Warning Covered by Current MR
4 Space before closing ** Standard MD037 Warning Covered by Current MR
5 Bold __ with parens __text(unit)__ Bash or Standard N/A Error/Warning Future MR
6 Spacing in __ (both sides) Standard MD037 Warning Covered by Current MR
7 Space after opening __ Standard MD037 Warning Covered by Current MR
8 Space before closing __ Standard MD037 Warning Covered by Current MR
9 Italic * with parens *text(unit)* Bash or Standard N/A Error/Warning Future MR
10 Spacing in * Standard MD037 Warning Covered by Current MR
11 Italic _ with parens _text(unit)_ Bash N/A Error Future MR
12 Spacing in _ Standard MD037 Warning Covered by Current MR
13 Fullwidth asterisks ＊ Custom MD-JA002 Warning Covered by Current MR
14 Fullwidth spaces 　 in emphasis Bash N/A Error Future MR
15 Four asterisks **** Custom MD-JA001 Warning Covered by Current MR
16 Three asterisks *** Bash N/A Warning Future MR

Why was this MR needed?

As explained above, we're currently experiencing a fair number of Translation Merge Requests having markdown issues specially with incorrect bolding and italics assignment. In this MR, we are creating a few markdown checks to warn the reviewers of these issues. Due to possible false positives, in our initial iteration, we'll only have them as warnings and will not fail the pipelines.

We currently have all of these changes merged to GitLab. Currently expanding this to GitLab Operator.

What's the best way to test this MR?

Step 1

To test these changes, we'd need markdown file(s) with one or more of the listed errors. I'm copying an existing file that's already available in runner.

autoscale.md

Step 2

Place them anywhere in /doc-locale/ja-jp (preferably under /doc-locale/ja-jp/test)

Step 3

cd /docs-locale

Run the following command

markdownlint-cli2 --config .markdownlint/.markdownlint-cli2.yaml ja-jp/test/autoscale.md

You should start seeing markdown errors listed in your terminal like"

markdownlint-cli2 v0.17.2 (markdownlint v0.37.4)
Finding: ja-jp/test/autoscale.md
Linting: 1 file(s)
Summary: 1 error(s)
ja-jp/test/autoscale.md:79:78 MD-JA001/no-four-asterisks Four consecutive asterisks (****) - likely a formatting error [Should have space between closing and opening bold markers] [Context: "`IdleCount = 0`を設定する場合には特別なモードもあります。このモードでは、（アイドル状態のマシンがない場合は）各ジョブの前にマシンが**常に****オンデマンド**で作成されます。ジョブが完了すると、オートスケールアルゴリズムは[以下の説明と同様に](#autoscaling-algorithm-and-parameters)動作します。マシンが次のジョブを待機しているが実行するジョブがない場合、`IdleTime`期間の経過後にマシンは削除されます。ジョブがない場合、アイドル状態のマシンはありません。"]

If you, however would like to run this on every markdown files on the current project, run the following command below:

markdownlint-cli2 --config .markdownlint/.markdownlint-cli2.yaml "ja-jp/**/*.md"

What are the relevant issue numbers?

Edited by Rasam Hossain

Merge request reports