GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — doc,tools: use only one level 1 header per page by Trott · Pull Request #37839 · nodejs/node

Conversation

@Trott

@Trott Trott commented Mar 20, 2021

Copy link
Copy Markdown
Member

First commit:

doc: reduce header nesting in async_hooks.md

Maximum header level reduced to 5.

Second commit:

doc,tools: use only one level 1 header per page

Increment the header levels from markdown files when producing HTML
documents. This is both better semantically (as the two h1 headers in
current docs are not actually equivalent level semantically--the second
belongs below/inside the first) and better for accessibility. (It is
valid HTML to have multiple h1 headers in a document, but it can be bad
for screen reader experience.)

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to Node.js documentation. tools Issues and PRs related to the tools directory. labels Mar 20, 2021
@Trott

Trott commented Mar 20, 2021

Copy link
Copy Markdown
Member Author

@aduh95 This ever-so-slightly changes the logic for the rendering optimization you added in #37301. (Sections now wrap <h3> instead of <h2> since I'm incrementing all the headers.) I don't think it has a negative affect, but PTAL.
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
aduh95
aduh95 reviewed Mar 20, 2021
View reviewed changes
Comment thread tools/doc/html.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread tools/doc/html.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
benjamingr
benjamingr approved these changes Mar 20, 2021
View reviewed changes
@aduh95

aduh95 commented Mar 20, 2021 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

This currently fails with this error:

Error: Cannot parse header tag with attributes
    at processContent (…/tools/doc/html.js:77:11)
    at Object.toHTML (…/tools/doc/html.js:105:46)
    at main (…/tools/doc/generate.js:97:29)
make: *** [out/doc/api/deprecations.html] Error 1

I think this is because of

node/tools/doc/html.js

Lines 402 to 409 in eaadc4b

const isDeprecationHeading =
DEPRECATION_HEADING_PATTERN.test(headingText);
if (isDeprecationHeading) {
if (!node.data) node.data = {};
if (!node.data.hProperties) node.data.hProperties = {};
node.data.hProperties.id =
headingText.substring(0, headingText.indexOf(':'));
}

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
aduh95
aduh95 reviewed Mar 20, 2021
View reviewed changes
Comment thread tools/doc/html.js Resolved

Uh oh!

There was an error while loading. Please reload this page.
marsonya
marsonya approved these changes Mar 21, 2021
View reviewed changes
jasnell
jasnell approved these changes Mar 22, 2021
View reviewed changes
PoojaDurgad
PoojaDurgad approved these changes Mar 23, 2021
View reviewed changes
@Trott
Trott force-pushed the h1 branch from 6e5288b to c186ade Compare March 24, 2021 05:45
aduh95
aduh95 approved these changes Mar 24, 2021
View reviewed changes
Trott added 2 commits March 25, 2021 11:23
@Trott
doc: reduce header nesting in async_hooks.md
8262f7a 
Maximum header level reduced to 5.

PR-URL: nodejs#37839
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Pooja D P <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
@Trott
doc,tools: use only one level 1 header per page
3700ba0 
Increment the header levels from markdown files when producing HTML
documents. This is both better semantically (as the two h1 headers in
current docs are not actually equivalent level semantically--the second
belongs below/inside the first) and better for accessibility. (It is
valid HTML to have multiple h1 headers in a document, but it can be bad
for screen reader experience.)

PR-URL: nodejs#37839
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Pooja D P <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
@Trott
Trott force-pushed the h1 branch from c186ade to 3700ba0 Compare March 25, 2021 18:29
@Trott
Trott merged commit 3700ba0 into nodejs:master Mar 25, 2021
@Trott

Trott commented Mar 25, 2021

Copy link
Copy Markdown
Member Author

d1e2184...3700ba0
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@Trott
Trott deleted the h1 branch March 25, 2021 18:29
ruyadorno pushed a commit that referenced this pull request Mar 29, 2021
@Trott @ruyadorno
doc: reduce header nesting in async_hooks.md
d30c263 
Maximum header level reduced to 5.

PR-URL: #37839
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Pooja D P <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
ruyadorno pushed a commit that referenced this pull request Mar 29, 2021
@Trott @ruyadorno
doc,tools: use only one level 1 header per page
e17b96b 
Increment the header levels from markdown files when producing HTML
documents. This is both better semantically (as the two h1 headers in
current docs are not actually equivalent level semantically--the second
belongs below/inside the first) and better for accessibility. (It is
valid HTML to have multiple h1 headers in a document, but it can be bad
for screen reader experience.)

PR-URL: #37839
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Pooja D P <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
ruyadorno pushed a commit that referenced this pull request Mar 30, 2021
@Trott @ruyadorno
doc: reduce header nesting in async_hooks.md
e84252b 
Maximum header level reduced to 5.

PR-URL: #37839
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Pooja D P <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
ruyadorno pushed a commit that referenced this pull request Mar 30, 2021
@Trott @ruyadorno
doc,tools: use only one level 1 header per page
3925458 
Increment the header levels from markdown files when producing HTML
documents. This is both better semantically (as the two h1 headers in
current docs are not actually equivalent level semantically--the second
belongs below/inside the first) and better for accessibility. (It is
valid HTML to have multiple h1 headers in a document, but it can be bad
for screen reader experience.)

PR-URL: #37839
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Pooja D P <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
@ruyadorno ruyadorno mentioned this pull request Mar 30, 2021
v15.13.0 proposal #37977
Merged
targos pushed a commit that referenced this pull request May 1, 2021
@Trott @targos
doc: reduce header nesting in async_hooks.md
b51651c 
Maximum header level reduced to 5.

PR-URL: #37839
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Pooja D P <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
targos pushed a commit that referenced this pull request May 1, 2021
@Trott @targos
doc,tools: use only one level 1 header per page
eb6ea85 
Increment the header levels from markdown files when producing HTML
documents. This is both better semantically (as the two h1 headers in
current docs are not actually equivalent level semantically--the second
belongs below/inside the first) and better for accessibility. (It is
valid HTML to have multiple h1 headers in a document, but it can be bad
for screen reader experience.)

PR-URL: #37839
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Pooja D P <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
@danielleadams danielleadams mentioned this pull request May 3, 2021
v14.17.0 proposal #38507
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jasnell jasnell jasnell approved these changes
@benjamingr benjamingr benjamingr approved these changes
@aduh95 aduh95 aduh95 approved these changes
@marsonya marsonya marsonya approved these changes
+1 more reviewer
@PoojaDurgad PoojaDurgad PoojaDurgad approved these changes
Reviewers whose approvals may not affect merge requirements

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

doc Issues and PRs related to Node.js documentation. tools Issues and PRs related to the tools directory.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

7 participants

@Trott @aduh95 @jasnell @benjamingr @marsonya @PoojaDurgad @nodejs-github-bot
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.