doc: consistent unordered list style by nschonni · Pull Request #29516 · nodejs/node · GitHub

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

Is there a preference for using * over -?

Prettier, a popular code formatter uses - over * as shows below:

> cat > test.md
Test
* One
* Two       
^C
> npx prettier test.md
Test

- One
- Two

I actually prefer - 😄 , I was just going by what looked like the more used format

I was just going by what looked like the more used format

Some results from grep in node repo:

> grep -r --include=\*.md '^* ' ./ | wc -l
   46352
> grep -r --include=\*.md '^\- ' ./ | wc -l
    6176

* is definitely more popular than - for first level of indentation

CI-lite: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3902/

This can be enforced with https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-ordered-list-marker-style afterwards

This PR accidentally altered YAML front-matter, breaking make doc.

It seems like an awfully big change set (1943 changed lines in its current form) and there might be other issues in there like this. I kind of doubt anyone actually reviewed all the changes here and instead rubber-stamped it. I'm not sure we should do it. It seems like we're doing it to be consistent for the sake of being consistent, which isn't terrible or anything, but it doesn't seem that using * in one file and - in another file is actually causing any issues for anyone. (Correction on that welcome.)

If it's possible to set the linter so that it requires one or the other in each file, but rejecting a mixture of both in a single file, that might be an acceptable first step towards eventually making them all consistent.

I'm not going to block this but I'm kind of -0 on it.

This PR accidentally altered YAML front-matter, breaking make doc.

Thanks, I'll take a look at that

If it's possible to set the linter so that it requires one or the other in each file, but rejecting a mixture of both in a single file, that might be an acceptable first step towards eventually making them all consistent.

Most of the changed files were because they were mixed

it doesn't seem that using * in one file and - in another file is actually causing any issues for anyone. (Correction on that welcome.)

Nope, different across docs is fine. The only issue that can really arise from mixed is if they are accidentally used at the same level, then multiple unorded lists are created. Can't recall if I actually saw any in here

CI: https://ci.nodejs.org/job/node-test-pull-request/25459/

make doc still failing because this PR still modifies YAML in a way that makes it invalid.

CI: https://ci.nodejs.org/job/node-test-pull-request/25461/

CI: https://ci.nodejs.org/job/node-test-pull-request/25463/

Convert to astericks when there are mixed styles in document. Addresses Markdownlint MD004 rule

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3909/

Landed in e2dcbf1

Convert to asterisks when there are mixed styles in document. Addresses Markdownlint MD004 rule PR-URL: #29516 Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

Thanks, I'll look at adding that to the remark-lint config if you don't get to it first

Convert to asterisks when there are mixed styles in document. Addresses Markdownlint MD004 rule PR-URL: #29516 Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

Erroneously removed in nodejs#29516. Fixes: nodejs#31810 Refs: nodejs#29516

Erroneously removed in #29516. Fixes: #31810 Refs: #29516 PR-URL: #31825 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Tobias Nießen <tniessen@tnie.de>

nodejs-github-bot added doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project. labels Sep 10, 2019

nschonni force-pushed the doc--consistent-unordered-list-style branch 2 times, most recently from bf53da5 to ad5de3b Compare September 10, 2019 06:07

devnexen approved these changes Sep 10, 2019

View reviewed changes

jasnell approved these changes Sep 11, 2019

View reviewed changes

trivikr approved these changes Sep 11, 2019

View reviewed changes

trivikr added the author ready PRs that have at least one approval, no outstanding review comments, and a CI started. label Sep 11, 2019

Trott removed the author ready PRs that have at least one approval, no outstanding review comments, and a CI started. label Sep 12, 2019