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: allow <code> in header elements #31086

Merged
merged 44 commits into from Dec 27, 2019
Merged

doc: allow <code> in header elements #31086

merged 44 commits into from Dec 27, 2019

Conversation

Trott
Copy link
Member

@Trott Trott commented Dec 25, 2019

First commit:

doc: allow <code> in header elements

Allow use of <code> in header elements without styling side effects. We
can add styling later if desired. The goal here is to allow code to be
set off in markdown without needing to escape characters and do lint
exceptions for terms. This is probably a win in terms of accessibility
too although it would be moreso if we had some visual differentiation
for <code> inside of headers. As mentioned above, that can always be
added at a later time.

Second commit:

doc,dns: use code markup/markdown in headers

This will allow us to lint for use of `hostname` in prose without
flagging `hostname` in code within headers. This also allows us to
remove backslash escaping for `[` and `]` inside of header code, which
makes the bare markdown more readable.

Subsequent commits make the change for all the other subsystems.

@nodejs/documentation

@nodejs/website (note the CSS changes)

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Dec 25, 2019
@Trott
Copy link
Member Author

Trott commented Dec 25, 2019

Probably easiest to review by looking at the first commit in isolation, and then the second commit in isolation. All the other commits follow suit from the second commit.

@Trott Trott added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Dec 25, 2019
Copy link
Contributor

@marswong marswong left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@@ -382,7 +382,7 @@ These advanced options are available for controlling decompression:
* Boolean flag enabling “Large Window Brotli” mode (not compatible with the
Brotli format as standardized in [RFC 7932][]).

## Class: Options
## Class: `Options`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Class: Options might be more harmonious than Class: Options

doc/api/v8.md Outdated Show resolved Hide resolved
doc/api/globals.md Show resolved Hide resolved
@Trott Trott force-pushed the header-code branch 2 times, most recently from 0bf5c62 to 8e3fd7c Compare December 25, 2019 05:39
@Trott
Copy link
Member Author

Trott commented Dec 25, 2019

Had to make a small change to tools/eslint-rules/documented-errors.js so that it would pass with the ` marks added to errors.md.

Copy link
Member

@nschonni nschonni left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, I've seen this over on the MS Docs that they use this approach as well because it is also an indicator that these are chunks that shouldn't be translated

Copy link
Member

@BridgeAR BridgeAR left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RSLGTM

Allow use of <code> in header elements without styling side effects. We
can add styling later if desired. The goal here is to allow code to be
set off in markdown without needing to escape characters and do lint
exceptions for terms. This is probably a win in terms of accessibility
too although it would be moreso if we had some visual differentiation
for <code> inside of headers. As mentioned above, that can always be
added at a later time.

PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
This will allow us to lint for use of `hostname` in prose without
flagging `hostname` in code within headers. This also allows us to
remove backslash escaping for `[` and `]` inside of header code, which
makes the bare markdown more readable.

PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: nodejs#31086
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants