From 7bfa0f27a6b3d63b344d459aca9f8067ac3da89b 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 e3d0d4251dcc7d..dd651a66c1e94f 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 67157ba6b5fb09..9089ce7e443232 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