Are the maintainers interested in markdownlinting for Hacktoberfest?

[pdelre]

Q	A
Version	n/a

Question

Would the maintainers be interested in PRs to improve the consistency of the markdown for Hacktoberfest? I had worked previously with thephpleague/commonmark to introduce markdownlint Action and take passes on correcting any discovered issues (Change List).

If so, I'd be happy to submit similar changes over the next few weeks. More information on Hacktoberfest and how they've improved the experience for maintainers this year is available here: https://hacktoberfest.digitalocean.com/resources/maintainers.

Checks before submitting

• [x] Be sure that there isn't already an issue about this. See: Issues list
• [x] Be sure that there isn't already a pull request about this. See: Pull requests
• [x] I have read, search and not found the information on the documentation website.
• [x] I have read, search and not found the information on PHP related forums and/or websites.
• [x] This issue is about 1 question around the package with no business or domain specific logic related to a specific situation.
• [x] The question has a descriptive title. For example: "Can I use the library with compressed CSV documents ?".

[nyamsprod]

@pdelre thanks for the suggestion as I am not really familiar with mardownlint could you please explain to me what you want to do exactly. Or better yet in the spirit of Hacktoberfest any help or improvement to this library is always welcomed. As always depending on the addition/reduction of maintenance work I will be more than happy to add that tool to make the library documentation better.

[pdelre]

Yes, it's purpose is pretty similar to other linters: enforce a standard (configurable) syntax based on a set of rules. Given that markdown generally does not have a strongly defined syntax, I've found this great to standardize across contributors. There's an additional opportunity to reuse the configuration from thephpleague/commonmark, providing consistency across thephpleague projects.

I've generally used JS's DavidAnson/markdownlint as it integrates nicely with VSCode. This version has the added advantage of being used by GitHub's Super-Linter Action, further reducing the CI maintenance cost.

As a preview of some "errors" that would be identified (and I'd resolve), here's some output I've generated locally.

docs/9.0/upgrading.md:17 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "~~~"]
docs/9.0/upgrading.md:17 MD048/code-fence-style Code fence style [Expected: backtick; Actual: tilde]
docs/9.0/upgrading.md:37 MD048/code-fence-style Code fence style [Expected: backtick; Actual: tilde]
docs/9.0/upgrading.md:49 MD048/code-fence-style Code fence style [Expected: backtick; Actual: tilde]
docs/9.0/upgrading.md:65 MD048/code-fence-style Code fence style [Expected: backtick; Actual: tilde]
docs/9.0/upgrading.md:71:1 MD010/no-hard-tabs Hard tabs [Column: 1]
docs/9.0/upgrading.md:72:1 MD010/no-hard-tabs Hard tabs [Column: 1]
docs/9.0/upgrading.md:79 MD048/code-fence-style Code fence style [Expected: backtick; Actual: tilde]
docs/9.0/upgrading.md:104 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Removed methods"]
docs/9.0/upgrading.md:121 MD048/code-fence-style Code fence style [Expected: backtick; Actual: tilde]
docs/9.0/upgrading.md:134 MD048/code-fence-style Code fence style [Expected: backtick; Actual: tilde]

[nyamsprod]

I'm not using VSCode but if the linter can make the documentation better and if I can easily integrate it within PHPStorm then please go ahead and proceed 😉

[pdelre]

and if I can easily integrate it within PHPStorm

That's a sticking point however. It can be integrated into the project's CI, but there are no JetBrains Plugins that I've found. At that point to integrate it into a local environment, it'd need to be installed via npm or run from a Docker container. This might not be a part of your workflow however as these tools are outside the immediate PHP developer community. I could add an entry to the composer.json's scripts but would require the command line tool to be installed manually.

[nyamsprod]

No need I always wanted to try out VSCode so it will be a good excuse for me to do so 😉

[pdelre]

@nyamsprod Thank you for working with me on these PRs! I have one final request, that you consider adding the label hacktoberfest-accepted to the PRs which will give me credit for the contributions. I promise to not ask again. 😆

Related PRs: #442 #443 #444 #445 #446

[nyamsprod]

@pdelre I added the labels let me know if I forgot any of the PR ... thanks for your work

[pdelre]

@nyamsprod Thank you!