Markdown Linting: remark-lint #16
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Ensuring that documentations and content written in Markdown [1] are of great quality should be a continuous goal of any project. Persisting information is a consistent and extensive way helps tp keep a project healthy, no matter whether for long-time or new users ad well as maintainers and contributors. Linting Markdown results in better rendering with different markdown parsers and makes sure less refactoring is needed afterwards. The best solution for this task would be a tool written in Go [2], but the undisputed best tool is still remark-lint [3] which is (unfortunately) written in JavaScript and used via NodeJS [4]. Of course there are fantastic projects written in Go like goldmark [5] that provides a great way to _parse_ content, but linting is (currently) not a feature. remark-lint on the other side is built on top of remark [6], the powerful Markdown processor powered by plugins (such as remark-lint itself) and part of the unifiedjs [7] collective. It comes with really large set of customizable rule [8] and ways to ensure Markdown will be consistent across any project. Another decision point for remark-lint was the fact that Prettier has been added in GH-13 to this template so Node is already a development dependency anyway. This also allows to add other awesome projects that are (unfortunately) written in JavaScript and for which there is no comparable alternative. >>> Configuration remark-lint can be used via remark-cli [npm-rcli] and a rule preset. This preset is remark-preset-lint-arcticicestudio [10], my custom preset that implements my Markdown Style Guide [11]. Since the custom preset is still in major version `0` the version range is `>=0.x.x <1.0.0` to avoid the "SemVer Major Zero Caveat". When defining package versions with the the carat `^` or tilde `~` range selector it won't affect packages with a major version of `0`. Yarn will resolve these packages to their exact version until the major version is greater or equal to `1`. To avoid this caveat the more detailed version range `>=0.x.x <1.0.0` is used to resolve all versions greater or equal to `0.x.x` but less than `1.0.0`. This will always use the latest `0.x.x` version and removes the need to increment the version manually on each new release. The `.remarkrc.js` configuration file is placed in the project root as well as the `.remarkignore` file to also define ignore pattern. >>> Package Script To allow to run the Markdown linting separately a `lint:md` package script has been added and included in the main `lint` script flow. [1]: https://en.wikipedia.org/wiki/Markdown [2]: https://go.dev [3]: https://github.com/remarkjs/remark-lint [4]: https://nodejs.org [5]: https://github.com/yuin/goldmard [6]: https://remark.js.org [7]: https://unifiedjs.com [8]: https://github.com/remarkjs/remark-lint/blob/master/doc/rules.md [9]: https://www.npmjs.com/package/remark-cli [10]: https://github.com/arcticicestudio/remark-preset-lint-arcticicestudio [11]: https://arcticicestudio.github.io/styleguide-markdown GH-15
svengreb
added a commit
that referenced
this pull request
Aug 22, 2020
Ensuring that documentations and content written in Markdown [1] are of great quality should be a continuous goal of any project. Persisting information is a consistent and extensive way helps tp keep a project healthy, no matter whether for long-time or new users ad well as maintainers and contributors. Linting Markdown results in better rendering with different markdown parsers and makes sure less refactoring is needed afterwards. The best solution for this task would be a tool written in Go [2], but the undisputed best tool is still remark-lint [3] which is (unfortunately) written in JavaScript and used via NodeJS [4]. Of course there are fantastic projects written in Go like goldmark [5] that provides a great way to _parse_ content, but linting is (currently) not a feature. remark-lint on the other side is built on top of remark [6], the powerful Markdown processor powered by plugins (such as remark-lint itself) and part of the unifiedjs [7] collective. It comes with really large set of customizable rule [8] and ways to ensure Markdown will be consistent across any project. Another decision point for remark-lint was the fact that Prettier has been added in GH-13 to this template so Node is already a development dependency anyway. This also allows to add other awesome projects that are (unfortunately) written in JavaScript and for which there is no comparable alternative. >>> Configuration remark-lint can be used via remark-cli [npm-rcli] and a rule preset. This preset is remark-preset-lint-arcticicestudio [10], my custom preset that implements my Markdown Style Guide [11]. Since the custom preset is still in major version `0` the version range is `>=0.x.x <1.0.0` to avoid the "SemVer Major Zero Caveat". When defining package versions with the the carat `^` or tilde `~` range selector it won't affect packages with a major version of `0`. Yarn will resolve these packages to their exact version until the major version is greater or equal to `1`. To avoid this caveat the more detailed version range `>=0.x.x <1.0.0` is used to resolve all versions greater or equal to `0.x.x` but less than `1.0.0`. This will always use the latest `0.x.x` version and removes the need to increment the version manually on each new release. The `.remarkrc.js` configuration file is placed in the project root as well as the `.remarkignore` file to also define ignore pattern. >>> Package Script To allow to run the Markdown linting separately a `lint:md` package script has been added and included in the main `lint` script flow. [1]: https://en.wikipedia.org/wiki/Markdown [2]: https://go.dev [3]: https://github.com/remarkjs/remark-lint [4]: https://nodejs.org [5]: https://github.com/yuin/goldmard [6]: https://remark.js.org [7]: https://unifiedjs.com [8]: https://github.com/remarkjs/remark-lint/blob/master/doc/rules.md [9]: https://www.npmjs.com/package/remark-cli [10]: https://github.com/arcticicestudio/remark-preset-lint-arcticicestudio [11]: https://arcticicestudio.github.io/styleguide-markdown Closes GH-15
svengreb
added a commit
that referenced
this pull request
Aug 22, 2020
Ensuring that documentations and content written in Markdown [1] are of great quality should be a continuous goal of any project. Persisting information is a consistent and extensive way helps tp keep a project healthy, no matter whether for long-time or new users ad well as maintainers and contributors. Linting Markdown results in better rendering with different markdown parsers and makes sure less refactoring is needed afterwards. The best solution for this task would be a tool written in Go [2], but the undisputed best tool is still remark-lint [3] which is (unfortunately) written in JavaScript and used via NodeJS [4]. Of course there are fantastic projects written in Go like goldmark [5] that provides a great way to _parse_ content, but linting is (currently) not a feature. remark-lint on the other side is built on top of remark [6], the powerful Markdown processor powered by plugins (such as remark-lint itself) and part of the unifiedjs [7] collective. It comes with really large set of customizable rule [8] and ways to ensure Markdown will be consistent across any project. Another decision point for remark-lint was the fact that Prettier has been added in GH-13 to this template so Node is already a development dependency anyway. This also allows to add other awesome projects that are (unfortunately) written in JavaScript and for which there is no comparable alternative. >>> Configuration remark-lint can be used via remark-cli [npm-rcli] and a rule preset. This preset is remark-preset-lint-arcticicestudio [10], my custom preset that implements my Markdown Style Guide [11]. Since the custom preset is still in major version `0` the version range is `>=0.x.x <1.0.0` to avoid the "SemVer Major Zero Caveat". When defining package versions with the the carat `^` or tilde `~` range selector it won't affect packages with a major version of `0`. Yarn will resolve these packages to their exact version until the major version is greater or equal to `1`. To avoid this caveat the more detailed version range `>=0.x.x <1.0.0` is used to resolve all versions greater or equal to `0.x.x` but less than `1.0.0`. This will always use the latest `0.x.x` version and removes the need to increment the version manually on each new release. The `.remarkrc.js` configuration file is placed in the project root as well as the `.remarkignore` file to also define ignore pattern. >>> Package Script To allow to run the Markdown linting separately a `lint:md` package script has been added and included in the main `lint` script flow. [1]: https://en.wikipedia.org/wiki/Markdown [2]: https://go.dev [3]: https://github.com/remarkjs/remark-lint [4]: https://nodejs.org [5]: https://github.com/yuin/goldmard [6]: https://remark.js.org [7]: https://unifiedjs.com [8]: https://github.com/remarkjs/remark-lint/blob/master/doc/rules.md [9]: https://www.npmjs.com/package/remark-cli [10]: https://github.com/arcticicestudio/remark-preset-lint-arcticicestudio [11]: https://arcticicestudio.github.io/styleguide-markdown Closes GH-15
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Resolves #15