doc: accommodate upcoming stricter .md linting - #52454
Conversation
Sorry, something went wrong.
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
|
Fast-track has been requested by @Trott. Please 👍 to approve. |
Sorry, something went wrong.
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.) |
Sorry, something went wrong.
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. |
Sorry, something went wrong.
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