Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: accommodate upcoming stricter .md linting #52454

Merged
merged 1 commit into from
Apr 10, 2024

Conversation

Trott
Copy link
Member

@Trott Trott commented Apr 10, 2024

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

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
@Trott Trott added the fast-track PRs that do not need to wait for 48 hours to land. label Apr 10, 2024
@nodejs-github-bot nodejs-github-bot added build Issues and PRs related to build files or the CI. doc Issues and PRs related to the documentations. labels Apr 10, 2024
Copy link
Contributor

Fast-track has been requested by @Trott. Please 👍 to approve.

@richardlau
Copy link
Member

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.

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?
https://github.com/nodejs/node/blob/main/BUILDING.md

(FWIW I'm personally fine with what this PR does, but I would not oppose moving them either.)

@Trott
Copy link
Member Author

Trott commented Apr 10, 2024

(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 Trott added the commit-queue Add this label to land a pull request using GitHub Actions. label Apr 10, 2024
@nodejs-github-bot nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Apr 10, 2024
@nodejs-github-bot nodejs-github-bot merged commit e9ccf5a into nodejs:main Apr 10, 2024
26 checks passed
@nodejs-github-bot
Copy link
Collaborator

Landed in e9ccf5a

marco-ippolito pushed a commit that referenced this pull request May 2, 2024
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>
marco-ippolito pushed a commit that referenced this pull request May 3, 2024
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
build Issues and PRs related to build files or the CI. doc Issues and PRs related to the documentations. fast-track PRs that do not need to wait for 48 hours to land.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants