Skip to content

Docs formatting checks using markdown linting

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

What does this MR do and why?

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.

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

References

https://gitlab.com/gitlab-com/localization/docs-site-localization/-/issues/597

Screenshots or screen recordings

Before After

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)がある場合、これらは環境のパフォーマンスに大きく影響することがあり、さらなる調整が必要になる場合があります**。これがあてはまると思われる場合は、必要に応じて追加のガイダンスについてお問い合わせください。"]

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Rasam Hossain

Merge request reports