Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from

Conversation

MicLieg
Copy link
Contributor

@MicLieg MicLieg commented Mar 7, 2024

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:

Fixes N/A

Type of change

  • Bug fix (a change which fixes an issue).
  • 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.

  • This pull request links to an issue.
  • This pull request uses the develop branch as its base.
  • This pull request subject follows the Conventional Commits standard.
  • This code follows the style guidelines of this project.
  • I have performed a self-review of my code.
  • I have checked that this code is commented where required.
  • I have provided a detailed enough description of this PR.
  • 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.

Thank you for your Pull Request!

@MicLieg
Copy link
Contributor Author

MicLieg commented Mar 8, 2024

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 GameServerManagers/LinuxGSM-Docs#104 and GameServerManagers/LinuxGSM-Dev-Docs#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
Copy link
Contributor Author

MicLieg commented Mar 8, 2024

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

@dgibbs64
Copy link
Member

dgibbs64 commented Mar 8, 2024

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
Copy link
Contributor Author

MicLieg commented Mar 8, 2024

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
Copy link
Member

dgibbs64 commented Mar 9, 2024

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
Copy link
Contributor Author

MicLieg commented Mar 9, 2024

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?
#4527 (comment)

@MicLieg MicLieg force-pushed the feature/recommend-extensions branch 2 times, most recently from 4803f3c to b409530 Compare April 24, 2024 11:36
@MicLieg MicLieg force-pushed the feature/recommend-extensions branch from a100d08 to 5e99f6b Compare August 6, 2024 13:43
@MicLieg MicLieg force-pushed the feature/recommend-extensions branch from 5e99f6b to 5cfe5bb Compare August 6, 2024 13:49
@MicLieg MicLieg force-pushed the feature/recommend-extensions branch from aae0a9a to 4d05908 Compare August 7, 2024 22:33
@MicLieg
Copy link
Contributor Author

MicLieg commented Aug 9, 2024

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 (GameServerManagers/LinuxGSM-Docs#104 & GameServerManagers/LinuxGSM-Dev-Docs#8) are ready for review, @dgibbs64.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants