Docs formatting checks using markdown linting - Charts

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

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

How to set up and validate locally

Step 1

To test these changes, we'd need markdown file(s) with one or more of the listed errors.

2k_users.md

Step 2

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

Step 3

cd /doc-locale

Run the following command

markdownlint-cli2 --config .markdownlint/.markdownlint-cli2.yaml ja-jp/test/2k_users.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/2k_users.md
Linting: 1 file(s)
Summary: 1 error(s)
ja-jp/test/2k_users.md:352:59 MD-JA001/no-four-asterisks Four consecutive asterisks (****) - likely a formatting error [Should have space between closing and opening bold markers] [Context: "**Gitalyの仕様は、正常に稼働する環境での利用パターンとリポジトリサイズの上位パーセンタイルに基づいています。****ただし、（数ギガバイトを超える）[大規模なモノレポ](_index.md#large-monorepos)または[追加のワークロード](_index.md#additional-workloads)がある場合、これらは環境のパフォーマンスに大きく影響することがあり、さらなる調整が必要になる場合があります**。これがあてはまると思われる場合は、必要に応じて追加のガイダンスについてお問い合わせください。"]

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"

This should give you the following result, indicating no error in the translated files in the current project:

markdownlint-cli2 v0.17.2 (markdownlint v0.37.4)
Finding: ja-jp/**/*.md
Linting: 26 file(s)
Summary: 0 error(s)

Related issues

Reference: gitlab-com/localization/docs-site-localization#727

Author checklist

For general guidance, please follow our Contributing guide.

Required

For anything in this list which will not be completed, please provide a reason in the MR discussion.

  • Merge Request Title and Description are up to date, accurate, and descriptive.
  • MR targeting the appropriate branch.
  • MR has a green pipeline.
  • Documentation created/updated.
  • Tests added/updated, and test plan for scenarios not covered by automated tests.
  • Equivalent MR/issue for omnibus-gitlab opened.

Reviewers checklist

Merge request reports