feat(vscode): Add DavidAnson.vscode-markdownlint extension

[MicLieg]

Description

This PR adds the VSCode extension vscode-markdownlint to the recommended extensions to help developers write more consistent Markdown by linting and style checking Markdown.

Related Pull Requests:

• https://github.com/GameServerManagers/LinuxGSM-Docs/pull/104
• https://github.com/GameServerManagers/LinuxGSM-Dev-Docs/pull/8

Fixes N/A

Type of change

• [ ] Bug fix (a change which fixes an issue).
• [x] New feature (a change which adds functionality).
• [ ] New Server (new server added).
• [ ] Refactor (restructures existing code).
• [ ] Comment update (typo, spelling, explanation, examples, etc).

Checklist

PR will not be merged until all steps are complete.

• [x] This pull request links to an issue.
• [x] This pull request uses the develop branch as its base.
• [x] This pull request subject follows the Conventional Commits standard.
• [x] This code follows the style guidelines of this project.
• [x] I have performed a self-review of my code.
• [x] I have checked that this code is commented where required.
• [x] I have provided a detailed enough description of this PR.
• [x] I have checked if documentation needs updating.

Documentation

If documentation does need updating either update it by creating a PR (preferred) or request a documentation update.

• User docs: https://github.com/GameServerManagers/LinuxGSM-Docs
• Dev docs: https://github.com/GameServerManagers/LinuxGSM-Dev-Docs

Thank you for your Pull Request!

[MicLieg]

It might be a good idea to also add Code Spell Checker to the list of recommended vscode extensions to easily catch spelling mistakes.

Creating a custom project-specific dictionary is as easy as creating a cspell.json file. Developers can then easily add false positive spelling errors to this file by hovering over the error and selecting Add: "Erroor" to config: ProjectFolder/cspell.json.

This also applies to https://github.com/GameServerManagers/LinuxGSM-Docs/pull/104 and https://github.com/GameServerManagers/LinuxGSM-Dev-Docs/pull/8, of course.

I'd be happy to add this to the pull requests and do a first sweep to collect project-specific words that don't exist in regular English dictionaries, like lgsm, glibcversion and gameserver.

[MicLieg]

Using this also allows LinuxGSM to use a GitHub Action to spell check all the code when pushing to a branch.

[dgibbs64]

I am currently using prettier https://prettier.io/ for formatting markdown. I believe I used to use this extension but it and Prettier didn't always agree so I chose to go with Prettier as it supports most of what I need. So in this case this extension might be redundant unless there is a specific requirement that might be useful

[MicLieg]

Unfortunately, that's correct.

However, I think it would be even better to coordinate the two, so that Prettier can do the quick formatting for developers, and markdownlint can check for convention compliance.

This would eliminate many Markdown "errors" from the docs and improve the uniformity across different files and repos.

A few examples where conventions are currently not being followed:

MD045/no-alt-text: Images should have alternate text (alt text)
MD036/no-emphasis-as-heading: Emphasis used instead of a heading
MD040/fenced-code-language: Fenced code blocks should have a language specified
MD001/heading-increment: Heading levels should only increment by one level at a time

One of the "disagreements" between the two is, for example, that Prettier would like to see 3 spaces after lists and markdownlint would like to see only 1 space

Prettier:

-   List Item 1
-   List Item 1

Markdownlint: MD030/list-marker-space: Spaces after list markers [Expected: 1; Actual: 3]

- List Item 1
- List Item 1

Since Prettier is known to be quite inflexible (for good reason!), markdownlint would have to give way here, which would not be difficult to configure in this case.

.markdownlint.json:

{
  "MD030": {
    "ul_single": 3,
    "ol_single": 3,
    "ul_multi": 3,
    "ol_multi": 3
  }
}

In the event that markdownlint is not sufficiently configurable, certain rules could be completely ignored.

[dgibbs64]

The other issue is that I use gitbook for the docs does have some of its own custom markdown I believe. So we need to keep an eye out for that. I use gitbook itself for editing the docs rather than the raw markdown. I am also unsure how compliant gitbook is with markdown.

I did notice that there is no one size fits all markdown standard which is annoying. But in general I like your suggestion. So the only thing I would add to this is the ignore rules for the markdown extension to prevent the markdown extention highlighting prettier conflicts.

[MicLieg]

Okay, i'll try to find as many conflicts as possible and configure markdownlint to either agree with prettier or ignore the conflicting rules.

Regarding GitBook it doesn't look like markdownlint has anything to say about GitBooks hint syntax:

{% hint style="success" %}
To exit debug mode use `CTRL+c`
{% endhint %}

Although it prefers regular Image embedding:

![Rocky Linux Logo](../.gitbook/assets/Rocky_Linux.png)

Instead of inline html:

<figure><img src="../.gitbook/assets/Rocky_Linux.png" alt=""><figcaption></figcaption></figure>

Which will result in: MD033/no-inline-html: Inline HTML [Element: img]

What do you think of Spell Checker? https://github.com/GameServerManagers/LinuxGSM/pull/4527#issuecomment-1985806692

[MicLieg]

prevent the markdown extention highlighting prettier conflicts

I made sure that markdownlint doesn't conflict with prettier by using the prettier ruleset as suggested by markdownlint

Now, this pull request and the linked ones (https://github.com/GameServerManagers/LinuxGSM-Docs/pull/104 & https://github.com/GameServerManagers/LinuxGSM-Dev-Docs/pull/8) are ready for review, @dgibbs64.