Add documentation for creating custom rules. Closes #261

[floroz]

This PR adds a a step by step guide on how to create and add a custom rule to remark-lint.

The newly created guide is also added as a new section in the readme.md.

• Closes Documentation and example on how to create custom rules #261

[floroz]

@wooorm cannot add reviewers but this PR is ready.

[wooorm]

Nice work! Here are a bunch of editorial suggestions. I’ll do a more content-focussed review next.

• Could you use ```sh for bash examples?
• Could you use ```markdown for markdown examples (I believe GH didn’t highlight md)?
• Could you remove $ from bash examples (when they don’t show output too). That dollar makes it hard to copy
• Could you match code-style to the one used in this project? Especially consistency with trailing commas and quote use
• Similarly, I see both // and /* comment styles, sometimes capitalized, sometimes not. Pick one, preferably capitalized.
• Could you use “smart” (curly) apostrophes? ’, not '
• Can you put enters after sentences? (helps with git diffs)
• I quite prefer reference style links [text][id] in prose and [id]: url at the bottom, can I persuade you to do that to?
• I’d prefer using npm in examples over yarn, as I believe npm is still more common thus match mores folks’ workflows

---

Here are some tools that can help you write better: https://github.com/get-alex/alex, https://wooorm.com/write-music/, https://wooorm.com/readability/.

You might also avoid hedges (https://github.com/words/hedges), fillers (https://github.com/words/fillers), and weasels (https://github.com/words/weasels).

[floroz]

Nice work! Here are a bunch of editorial suggestions. I’ll do a more content-focussed review next.

• Could you use ```sh for bash examples?
• Could you use ```markdown for markdown examples (I believe GH didn’t highlight md)?
• Could you remove $ from bash examples (when they don’t show output too). That dollar makes it hard to copy
• Could you match code-style to the one used in this project? Especially consistency with trailing commas and quote use
• Similarly, I see both // and /* comment styles, sometimes capitalized, sometimes not. Pick one, preferably capitalized.
• Could you use “smart” (curly) apostrophes? ’, not '
• Can you put enters after sentences? (helps with git diffs)
• I quite prefer reference style links [text][id] in prose and [id]: url at the bottom, can I persuade you to do that to?
• I’d prefer using npm in examples over yarn, as I believe npm is still more common thus match mores folks’ workflows

Here are some tools that can help you write better: https://github.com/get-alex/alex, https://wooorm.com/write-music/, https://wooorm.com/readability/.

You might also avoid hedges (https://github.com/words/hedges), fillers (https://github.com/words/fillers), and weasels (https://github.com/words/weasels).

That's some great feedback, thank you!

I have addressed your comments, I am just not sure about:

• I quite prefer reference style links [text][id] in prose and [id]: url at the bottom, can I persuade you to do that to?

Would you mind help me understand more about this?

[wooorm]

Would you mind help me understand more about this?

See the alternative version of links here: https://commonmark.org/help/. And see examples in the readme: https://raw.githubusercontent.com/remarkjs/remark-lint/main/readme.md

[floroz]

Would you mind help me understand more about this?

See the alternative version of links here: https://commonmark.org/help/. And see examples in the readme: https://raw.githubusercontent.com/remarkjs/remark-lint/main/readme.md

Got it! didn't know that alternative syntax.

If that's okay with you I would prefer leaving them as they are, ultimately they live in a separate file so they won't be creating any confusion with the other readme.md docs.

Besides that, everything else should have been fixed, let me know if you are happy to merge it!

[wooorm]

Nice! Some more nits. (btw: did you know you can commit these suggestions through the GH UI? Just checking, that’ll help speed things up).
Other than these nits the article reads great!

[floroz]

Nice! Some more nits. (btw: did you know you can commit these suggestions through the GH UI? Just checking, that’ll help speed things up).
Other than these nits the article reads great!

Thanks for taking the time to review in such details!

Yes I am aware, I generally review/work on PR directly within VS Code using the GitHub PR Extension, but considering the number of changes request this time I used the GH UI.
I am curious though, was there a way for me to accept all suggestions at once in a single commit?

[ChristianMurphy]

I am curious though, was there a way for me to accept all suggestions at once in a single commit?

In the "files changed" tab, it should offer to add changes to a batch, which will be a single commit.
https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request

[floroz]

I am curious though, was there a way for me to accept all suggestions at once in a single commit?

In the "files changed" tab, it should offer to add changes to a batch, which will be a single commit.
https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request

Thank you @ChristianMurphy ! That's really handy to know 😄 sorry about the commit spam then!

[wooorm]

Awesome!

[wooorm]

Thanks for all your work on this, @floroz!

[floroz]

Thanks for all your work on this, @floroz!

Thanks for the feedback, happy to help!