doc,tools: syntax highlight api docs at compile-time

tolmasky · addaleax · commit 7b29c9194400 · 2020-09-22T19:53:46.000+02:00
Prior to this commit, API docs would be highlighted after the page loaded using `highlightjs`. This commit still uses `highlightjs`, but runs the generation during the compilation of the documentation, making it so no script needs to load on the client. This results in a faster load, as well as allowing the pages to fully functional even when JavaScript is turned off. PR-URL: #34148 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>
diff --git a/doc/api_assets/README.md b/doc/api_assets/README.md
@@ -1,28 +1,9 @@
 # API Reference Document Assets
 
-## highlight.pack.js
-
-_Generated by [highlightjs.org/download][] on 2020-06-07._
-
-Grammars included in the custom bundle:
-
-* Bash
-* C
-* C++
-* CoffeeScript
-* HTTP
-* JavaScript
-* JSON
-* Markdown
-* Plaintext
-* Shell Session
-
 ## hljs.css
 
 The syntax theme for code snippets in API reference documents.
 
 ## style.css
 
 The main stylesheet for API reference documents.
-
-[highlightjs.org/download]: https://highlightjs.org/download/
diff --git a/doc/api_assets/highlight.pack.js b/doc/api_assets/highlight.pack.js
diff --git a/doc/template.html b/doc/template.html
@@ -3,6 +3,7 @@
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width">
+  <meta name="nodejs.org:node-version" content="__VERSION__">
   <title>__SECTION__ | Node.js __VERSION__ Documentation</title>
   <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
   <link rel="stylesheet" href="assets/style.css">
@@ -48,10 +49,9 @@ <h2>Table of Contents</h2>
 
       <div id="apicontent">
         __CONTENT__
+        <!-- API END -->
       </div>
     </div>
   </div>
-  <script src="assets/highlight.pack.js"></script>
-  <script>document.addEventListener('DOMContentLoaded', () => { hljs.initHighlightingOnLoad(); });</script>
 </body>
 </html>
diff --git a/tools/doc/allhtml.js b/tools/doc/allhtml.js
@@ -37,7 +37,7 @@ for (const link of toc.match(/<a.*?>/g)) {
     .replace(/[\s\S]*?<div id="toc">\s*<h2>.*?<\/h2>\s*(<ul>\s*)?/, '');
 
   apicontent += data.slice(match.index + match[0].length)
-    .replace(/(<\/div>\s*)*\s*<script[\s\S]*/, '')
+    .replace(/<!-- API END -->[\s\S]*/, '')
     .replace(/<a href="(\w[^#"]*)#/g, (match, href) => {
       return htmlFiles.includes(href) ? '<a href="#' : match;
     })
@@ -66,10 +66,10 @@ all = all.slice(0, tocStart.index + tocStart[0].length) +
 
 // Replace apicontent with the concatenated set of apicontents from each source.
 const apiStart = /<div id="apicontent">\s*/.exec(all);
-const apiEnd = /(\s*<\/div>)*\s*<script /.exec(all);
+const apiEnd = all.lastIndexOf('<!-- API END -->');
 all = all.slice(0, apiStart.index + apiStart[0].length) +
   apicontent +
-  all.slice(apiEnd.index);
+  all.slice(apiEnd);
 
 // Write results.
 fs.writeFileSync(source + '/all.html', all, 'utf8');
diff --git a/tools/doc/html.js b/tools/doc/html.js
@@ -32,6 +32,7 @@ const raw = require('rehype-raw');
 const htmlStringify = require('rehype-stringify');
 const path = require('path');
 const typeParser = require('./type-parser.js');
+const { highlight, getLanguage } = require('highlight.js');
 
 module.exports = {
   toHTML, firstHeader, preprocessText, preprocessElements, buildToc
@@ -183,6 +184,21 @@ function preprocessElements({ filename }) {
       if (node.type === 'heading') {
         headingIndex = index;
         heading = node;
+      } else if (node.type === 'code') {
+        if (!node.lang) {
+          console.warn(
+            `No language set in ${filename}, ` +
+            `line ${node.position.start.line}`);
+        }
+        const language = (node.lang || '').split(' ')[0];
+        const highlighted = getLanguage(language) ?
+          highlight(language, node.value).value :
+          node.value;
+        node.type = 'html';
+        node.value = '<pre>' +
+          `<code class = 'language-${node.lang}'>` +
+          highlighted +
+          '</code></pre>';
       } else if (node.type === 'html' && common.isYAMLBlock(node.value)) {
         node.value = parseYAML(node.value);
 
diff --git a/tools/doc/package-lock.json b/tools/doc/package-lock.json
diff --git a/tools/doc/package.json b/tools/doc/package.json
@@ -7,6 +7,7 @@
     "node": ">=12.10.0"
   },
   "dependencies": {
+    "highlight.js": "^9.18.1",
     "rehype-raw": "^2.0.0",
     "rehype-stringify": "^3.0.0",
     "remark-html": "^7.0.0",
