From eb6ea8501b3e7257addf5f795b73357bc5d8e3ba Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 20 Mar 2021 07:21:36 -0700 Subject: [PATCH] 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.) PR-URL: https://github.com/nodejs/node/pull/37839 Reviewed-By: Benjamin Gruenbaum Reviewed-By: James M Snell Reviewed-By: Pooja D P Reviewed-By: Antoine du Hamel --- test/doctool/test-doctool-html.js | 38 +++++++++++++++---------------- tools/doc/html.js | 17 ++++++++++---- 2 files changed, 32 insertions(+), 23 deletions(-) diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js index 97c37dece88534..2fa4766c837a27 100644 --- a/test/doctool/test-doctool-html.js +++ b/test/doctool/test-doctool-html.js @@ -60,25 +60,25 @@ function toHTML({ input, filename, nodeVersion, versions }) { const testData = [ { file: fixtures.path('order_of_end_tags_5873.md'), - html: '

Static method: Buffer.from(array) ' + + html: '

Static method: Buffer.from(array) ' + '#

' + + 'id="foo_static_method_buffer_from_array">#

' + '' }, { file: fixtures.path('doc_with_yaml.md'), - html: '

Sample Markdown with YAML info' + + html: '

Sample Markdown with YAML info' + '#

' + - '

Foobar#

' + + ' id="foo_sample_markdown_with_yaml_info">#' + + '

Foobar#

' + '
Added in: v1.0.0
' + '

Describe Foobar in more detail here.

' + '
' + - '

Foobar II#

' + + '

Foobar II#

' + '
History' + '' + '' + @@ -88,15 +88,15 @@ const testData = [ '

Describe Foobar II in more detail here.' + 'fg(1)' + '

' + - '

Deprecated thingyDeprecated thingy#' + - '

Added in: v1.0.0' + + '
Added in: v1.0.0' + 'Deprecated since: v2.0.0

Describe ' + 'Deprecated thingy in more detail here.' + 'fg(1p)' + '

' + - '

Something#

' + + '

Something#

' + ' ' + '

Describe Something in more detail here.

' }, @@ -111,19 +111,19 @@ const testData = [ }, { file: fixtures.path('document_with_links.md'), - html: '

Usage and ExampleUsage and Example#' + - '

Usage#

node \\[options\\] index.js' + + '

Usage#

node \\[options\\] index.js' + '

Please see the' + 'Command Line Optionsdocument for more information.

' + - '

' + + '

' + 'Example' + - '#

An example of a' + + '#

An example of a' + 'webserverwritten with Node.js which responds with' + '\'Hello, World!\':

' + - '

See also#

Check' + + '

See also#

Check' + 'out alsothis guide

' }, { diff --git a/tools/doc/html.js b/tools/doc/html.js index b519fd9c5a805b..39062840641e94 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -66,10 +66,19 @@ const gtocHTML = unified() const templatePath = path.join(docPath, 'template.html'); const template = fs.readFileSync(templatePath, 'utf8'); -function wrapSections(content) { +function processContent(content) { + content = content.toString(); + // Increment header tag levels to avoid multiple h1 tags in a doc. + // This means we can't already have an
. + if (content.includes('
')) { + throw new Error('Cannot increment a level 6 header'); + } + // `++level` to convert the string to a number and increment it. + content = content.replace(/(?<=<\/?h)[1-5](?=[^<>]*>)/g, (level) => ++level); + // Wrap h3 tags in section tags. let firstTime = true; - return content.toString() - .replace(/

{ + return content + .replace(/

{ if (firstTime) { firstTime = false; return '
' + heading; @@ -91,7 +100,7 @@ function toHTML({ input, content, filename, nodeVersion, versions }) { .replace('__GTOC__', gtocHTML.replace( `class="nav-${id}"`, `class="nav-${id} active"`)) .replace('__EDIT_ON_GITHUB__', editOnGitHub(filename)) - .replace('__CONTENT__', wrapSections(content)); + .replace('__CONTENT__', processContent(content)); const docCreated = input.match( //);

VersionChanges
v5.3.0, v4.2.0