Skip to content

doc: add in guide generation using remark #5408

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
wants to merge 1 commit into from
Closed

doc: add in guide generation using remark #5408

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
4 changes: 4 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,10 @@ apidoc_dirs = out/doc out/doc/api/ out/doc/api/assets

apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*)))

docguide:
mkdir -p out/doc/guides
$(NODE) tools/doc/guide.js

doc: $(apidoc_dirs) $(apiassets) $(apidocs) tools/doc/ $(NODE_EXE)

$(apidoc_dirs):
Expand Down
32 changes: 32 additions & 0 deletions doc/template-guide.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Node.js __VERSION__ Manual &amp; Guide</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic">
<link rel="stylesheet" href="assets/style.css">
<link rel="stylesheet" href="assets/sh.css">
<link rel="canonical" href="https://nodejs.org/guides/__FILENAME__.html">
</head>
<body class="alt apidoc" id="api-section-__FILENAME__">
<div id="content" class="clearfix">
<div id="column2" class="interior">
<div id="intro" class="interior">
<a href="/" title="Go back to the home page">
Node.js (1)
</a>
</div>
__GTOC__
</div>

<div id="column1" data-id="__ID__" class="interior">
<div id="apicontent">
__CONTENT__
</div>
</div>
</div>
<script src="assets/sh_main.js"></script>
<script src="assets/sh_javascript.min.js"></script>
<script>highlight(undefined, undefined, 'pre');</script>
</body>
</html>
53 changes: 53 additions & 0 deletions tools/doc/guide.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
const path = require('path');
Copy link
Contributor

@thefourtheye thefourtheye Feb 25, 2016

Choose a reason for hiding this comment

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

Shouldn't this file be running in strict mode?

const fs = require('fs');

const remark = require('remark');
const html = require('remark-html');
const toc = require('remark-toc');
const hljs = require('remark-highlight.js');

const processor = remark()
.use(toc)
.use(html)
.use(hljs)
const remarkOptions = {
yaml: true,
bullet: '*'
}

const guidesDir = path.join(__dirname, '../../', 'doc', 'guides');
const outputDir = path.join(__dirname, '../../', 'out', 'doc', 'guides');
const templateFile = path.join(__dirname, '../../', 'doc', 'template-guide.html');
const template = fs.readFileSync(templateFile, { encoding: 'utf8' })

fs.readdir(guidesDir, function(err, files) {
if (err) {
throw err;
}
files.forEach(function(fileName) {
const pageSlug = path.basename(fileName, '.md');
fs.readFile(path.join(guidesDir, fileName), { encoding: 'utf8' }, function(err, content) {
Copy link
Contributor

@thefourtheye thefourtheye Feb 25, 2016

Choose a reason for hiding this comment

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

Don't ignore err

var mdast = processor.parse(content, remarkOptions);
mdast = processor.run(mdast);
const html = processor.stringify(mdast, remarkOptions);
// Locate YAML front matter
if (mdast.children[0] && mdast.children[0].type === 'yaml') {
Copy link

@DavidTPate DavidTPate Feb 24, 2016

Choose a reason for hiding this comment

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

Why not use a YAML parser such as js-yaml? Currently this code wouldn't support the full YAML specification, which could be confusing for people expecting to be able to write true YAML within the docs.

// Found YAML
var yamlData = {}
mdast.children[0].value.split('\n').forEach(function(line) {
const keyValue = line.match(/(\w+):\s?(.+)/)
Copy link

@DavidTPate DavidTPate Feb 24, 2016

Choose a reason for hiding this comment

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

I'm thinking that at some point we'll want to have comments in the YAML. We should probably handle the line beginning with # as well.

Copy link

@DavidTPate DavidTPate Feb 24, 2016

Choose a reason for hiding this comment

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

This also won't currently match all of the values allowed for a key with YAML. Things can be escaped, in quotes, have dashes, etc.

Copy link
Author

@kahwee kahwee Feb 24, 2016

Choose a reason for hiding this comment

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

I was trying to reduce external dependencies. But you made a good point.

yamlData[keyValue[1]] = keyValue[2]
})
// console.log(yamlData)
}
var output = template.replace(/__VERSION__/g, process.version);
output = output.replace(/__CONTENT__/g, html);
output = output.replace(/__FILENAME__/g, pageSlug);
fs.writeFile(path.join(outputDir, pageSlug + '.html'), output, function(err) {
if (err) {
throw err;
}
})
})
})
})
6 changes: 5 additions & 1 deletion tools/doc/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,11 @@
"node": ">=0.6.10"
},
"dependencies": {
"marked": "~0.1.9"
"marked": "~0.1.9",
"remark": "^3.2.2",
"remark-highlight.js": "^3.0.0",
"remark-html": "^3.0.0",
"remark-toc": "^3.0.0"
},
"devDependencies": {},
"optionalDependencies": {},
Expand Down