doc,tools: Replace client-side syntax highlighting for API docs compile compile-time syntax highlighting

tolmasky · tolmasky · commit 8beb9443165b · 2020-07-02T17:06:57.000-07:00
1. The page will load much faster since there is much less JavaScript taking place.
2. Users with slow connections or JavaScript turned off will still see highlighted code.
3. I've changed the allhtml.js code to look for a special comment instead of the script tag for where to put the contents.
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('highlightjs');
 
 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
@@ -16,7 +16,8 @@
     "unified": "^7.0.0",
     "unist-util-find": "^1.0.1",
     "unist-util-select": "^1.5.0",
-    "unist-util-visit": "^1.4.0"
+    "unist-util-visit": "^1.4.0",
+    "highlightjs": "^9.10.0"
   },
   "devDependencies": {
     "js-yaml": "^3.13.1"
