doc: accommodate upcoming stricter .md linting #52454
Conversation
remark-lint-final-definition@4.0.0 will start flagging footnotes in BUILDING.md. I don't think we want to move them to the bottom, so I've disabled the lint rule where relevant. Ref: nodejs/remark-preset-lint-node#511
nodejs-github-bot
added
build
|
Fast-track has been requested by @Trott. Please 👍 to approve. |
On the other hand, GitHub renders the footnotes at the bottom of the page, so maybe moving them would be more consistent with how the doc gets rendered? (FWIW I'm personally fine with what this PR does, but I would not oppose moving them either.) |
Yeah, I could go either way. Leaving them where they are makes the file more usable/readable for someone reading it as plain text. For our API docs, that would not be a big deal from my perspective as I imagine most people read them on GitHub or on our web page. But for BUILDING.md, I imagine (but don't have any hard data to back up my intuition) that people read it as plain text a decent percentage of the time. But moving them to the bottom is still usable/readable as plaintext, if less convenient. And it means avoiding the rule-disabling comments, which are mildly annoying from a read-as-plain-text perspective. So either way would be fine from my perspective. But I just want to get one landed so that we can update the lint preset package. We can always switch from one way to the other at a later date. |
Trott
added
the
commit-queue
nodejs-github-bot
removed
the
commit-queue
|
Landed in e9ccf5a |
remark-lint-final-definition@4.0.0 will start flagging footnotes in BUILDING.md. I don't think we want to move them to the bottom, so I've disabled the lint rule where relevant. Ref: nodejs/remark-preset-lint-node#511 PR-URL: #52454 Refs: nodejs/remark-preset-lint-node#511 Reviewed-By: Yagiz Nizipli <yagiz.nizipli@sentry.io> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de>
remark-lint-final-definition@4.0.0 will start flagging footnotes in BUILDING.md. I don't think we want to move them to the bottom, so I've disabled the lint rule where relevant. Ref: nodejs/remark-preset-lint-node#511 PR-URL: #52454 Refs: nodejs/remark-preset-lint-node#511 Reviewed-By: Yagiz Nizipli <yagiz.nizipli@sentry.io> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de>
remark-lint-final-definition@4.0.0 will start flagging footnotes in BUILDING.md. I don't think we want to move them to the bottom, so I've disabled the lint rule where relevant.
Ref: nodejs/remark-preset-lint-node#511