Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
tolmasky wants to merge 1 commit into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 0 additions & 19 deletions doc/api_assets/README.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -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/
6 changes: 0 additions & 6 deletions doc/api_assets/highlight.pack.js
View file
Open in desktop

This file was deleted.

4 changes: 2 additions & 2 deletions doc/template.html
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<meta name="nodejs.org:node-version" content="__VERSION__">
Copy link
Contributor

@DerekNonGenericDerekNonGenericJul 15, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tolmasky, would you mind explaining what this meta tag will be used for (if anything)?

Copy link
Contributor

@DerekNonGenericDerekNonGenericJul 15, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem it solves is that there is currently no easy way to determine what version of the docs you are viewing without falling back regex hacks on the title or h1 element, which should probably not be relied on as a future-proof method, especially when localizing the docs. The URL itself also isn't reliable since these docs often live at vXX-latest. This meta tag provides a place you can reliably query the version of the node docs, whether as a script on the page (as in the other commit), or a program operating on the page (for example if you are running end-to-end tests with puppeteer), or even when visually comparing a diff.
— #34148 (comment)

I wonder if this meta tag would be useful for @zeke's localization work.

<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">
Expand DownExpand Up@@ -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>
6 changes: 3 additions & 3 deletions tools/doc/allhtml.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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;
})
Expand DownExpand Up@@ -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');
Expand Down
16 changes: 16 additions & 0 deletions tools/doc/html.js
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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
Expand DownExpand Up@@ -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);

Expand Down
5 changes: 5 additions & 0 deletions tools/doc/package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions tools/doc/package.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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",
Expand Down