doc,tools: Replace client-side syntax highlighting for API docs compi…

…le compile-time syntax highlighting 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.
nodejs · Jul 3, 2020 · 8beb944 · 8beb944
1 parent 1dc837e
commit 8beb944
Show file tree

Hide file tree

Showing 7 changed files with 28 additions and 31 deletions.
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"