doc: prepare miscellaneous docs for new markdown lint rules #29963
Conversation
nodejs-github-bot
added
doc
|
Collaborators, please 👍 here to fast-track. |
test/common/README.md
Outdated
| * `buf` [<Buffer>] | ||
| * return [<ArrayBufferView[]>] | ||
| * `buf` [<Buffer>][] | ||
| * return [<ArrayBufferView>][]\[\] |
There was a problem hiding this comment.
Think the reference link might need to be updated instead for the 3 in this section to include the array modifier in the identifier
There was a problem hiding this comment.
The current way does work though
There was a problem hiding this comment.
My thinking in preferring this way is that the linked info is not about ArrayBufferView[]. It's about ArrayBufferView. So the link text reflects that.
Trott
added
the
author ready
|
Escaping the square brackets is not needed AFAICT. Which tool complains? EDIT: For example, this shows just fine without escaping |
It makes the text a link (without displaying brackets at all) if the text happens to match a bottom-reference, which it did in one case that @nschonni found. So it only causes problems infrequently. Or at least that's my understanding. Maybe @nschonni can confirm/clarify. |
|
The instance this did flag correctly was #29809 (comment) and the rule that flags it is https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-undefined-references |
And in the current version of the docs (for 12.12.0), you can see the problem: https://nodejs.org/dist/latest-v12.x/docs/api/crypto.html#crypto_diffiehellman_generatekeys_encoding The brackets are gone and "encoding" is now link text. |
|
From the upstream build failure, there are a few new ones in doc/api/vm.md |
Good to know. I'm OK with fixing those up when the lint rule lands on master, just as long as there's three lines to fix and not 150. |
|
It's no big deal, I'm just trying to understand why perfectly fine square brackets are flagged. Are the docs being built here on CI? Is the output the same? |
Docs are built on CI so that if any changes to the docs happen that break doctool or whatever, we know. I don't think that output is checked, but I don't have any reason to believe it's different than when people run locally. |
|
Landed in ed5eaa0 |
Trott
force-pushed
the
update-md-linting
branch
from
da5538f
to
ed5eaa0
Compare
Prepare the final few documents that haven't been updated to always use `[]` with reference links and to escape `[` and `]` for things that aren't links in markdown files. PR-URL: #29963 Reviewed-By: Masashi Hirano <shisama07@gmail.com> Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Prepare the final few documents that haven't been updated to always use `[]` with reference links and to escape `[` and `]` for things that aren't links in markdown files. PR-URL: #29963 Reviewed-By: Masashi Hirano <shisama07@gmail.com> Reviewed-By: David Carlier <devnexen@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Prepare the final few documents that haven't been updated to always use
[]with reference links and to escape[and]for things thataren't links in markdown files.
These are the final changes required before we can use the next version of remark-preset-lint-node.
@nschonni @nodejs/documentation
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes