Use a dedicated formatter/linter for Markdown files (#75)

* Install markdownlint-cli2

* Change indentation to 2 spaces for Markdown

* Add useful VS Code settings for Markdown

* Add better refs for EditorConfig options for Markdown

* Avoid formatting Markdown files with Prettier

* Add npm scripts to run markdownlint via CLI

* Add a configuration file

* Disable trailing commas in JSONC files

See prettier/prettier#15956.

.editorconfig

@@ -20,11 +20,16 @@ indent_style = tab
 
 # Markdown files
 [*.md]
-# Keep trailing whitespace in order to create hard line breaks (see https://code.visualstudio.com/docs/languages/markdown#_keep-trailing-whitespace-in-order-to-create-line-breaks)
-trim_trailing_whitespace = false
-# 4-spaces indentation (see https://github.com/DavidAnson/vscode-markdownlint/issues/86#issuecomment-579860824)
+# Ref: https://github.com/DavidAnson/markdownlint/blob/main/doc/md010.md
 indent_style = space
-indent_size = 4
+# Ref: https://github.com/DavidAnson/markdownlint/blob/main/doc/md007.md
+indent_size = 2
+# Refs:
+# https://cirosantilli.com/markdown-style-guide/#line-breaks
+# https://www.markdownguide.org/basic-syntax/#line-breaks
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/md009.md
+# https://code.visualstudio.com/docs/languages/markdown#_keep-trailing-whitespace-in-order-to-create-line-breaks
+trim_trailing_whitespace = false
 
 # YAML files
 [*.{yml,yaml}]

.markdownlint-cli2.jsonc

@@ -0,0 +1,48 @@
+// I use the .markdownlint-cli2.jsonc configuration file because it enables auto-completion in VS Code when using the extension. More info: https://github.com/DavidAnson/markdownlint-cli2/blob/main/README.md#markdownlint-cli2jsonc.
+
+{
+	"globs": ["**.md"], // Lint all .md files in the current directory and its subdirectories
+	"config": {
+		"default": true,
+		"code-block-style": {
+			"style": "fenced"
+		},
+		"code-fence-style": {
+			"style": "backtick"
+		},
+		"emphasis-style": {
+			"style": "asterisk"
+		},
+		"heading-style": {
+			"style": "atx"
+		},
+		"hr-style": {
+			"style": "---"
+		},
+		"line-length": false,
+		"no-blanks-blockquote": false, // Allow consecutive blockquotes/alerts/callouts
+		"no-duplicate-heading": {
+			"siblings_only": true
+		},
+		"no-inline-html": false,
+		"no-trailing-punctuation": {
+			"punctuation": ".,;:。，；：" // Allow '!' and '！' (default is ".,;:!。，；：！")
+		},
+		"no-trailing-spaces": {
+			"strict": true
+		},
+		"ol-prefix": {
+			"style": "ordered"
+		},
+		"strong-style": {
+			"style": "asterisk"
+		},
+		"table-pipe-style": {
+			"style": "leading_and_trailing"
+		},
+		"ul-style": {
+			"style": "dash"
+		}
+	},
+	"gitignore": true
+}

.prettierignore

@@ -3,3 +3,6 @@
 # - node_modules
 # Prettier will also follow rules specified in the ".gitignore" file if it exists in the same directory from which it is run.
 # Reference: https://prettier.io/docs/en/ignore.html.
+
+# Ignore all Markdown files (use markdownlint-cli2 instead)
+**/*.md

.prettierrc.json

@@ -9,6 +9,12 @@
 		{
 			"files": ["*.js", "*.jsx", "*.vue"],
 			"options": { "singleAttributePerLine": true }
+		},
+		{
+			"files": ["*.jsonc"],
+			"options": {
+				"trailingComma": "none"
+			}
 		}
 	]
 }

.vscode/settings.json

@@ -1,6 +1,10 @@
 {
 	// Formatting
 	"editor.defaultFormatter": "esbenp.prettier-vscode",
+	"[markdown]": {
+		"editor.defaultFormatter": "DavidAnson.vscode-markdownlint",
+		"editor.renderWhitespace": "boundary"
+	},
 	"editor.formatOnSave": true,
 	// Lint CSS with Stylelint
 	"stylelint.enable": true, // default
@@ -12,6 +16,7 @@
 		// As object, "source.fixAll" actions are prioritized and executed first.
 		// Ref: https://github.com/microsoft/vscode/blob/1.90.0/src/vs/workbench/contrib/codeEditor/browser/saveParticipants.ts#L300-L332.
 		"source.fixAll.eslint": "explicit",
+		"source.fixAll.markdownlint": "explicit",
 		"source.fixAll.stylelint": "explicit",
 		"source.addMissingImports": "explicit",
 		"source.sortImports": "explicit"