doc: add in guide generation using remark

[kahwee]

Do not merge.

I did not commit in node_modules. This intends to generate guides, it is related to #4866. This generates HTML from MarkDown and implements highlight.js.

Currently it generates building-node-with-ninja.md into corresponding HTML.

To run it:

cd tools/doc
npm i
cd ../../
make docguide

This differs from #4866 by being group processing Markdown guide files.

CC: @nodejs/documentation

By the way, if I commit in node_modules, there are a lot of files going in. Is this an approach we should proceed with?

[DavidTPate]

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.

[silverwind]

Regarding node_modules, I'd suggest

1. install them with NODE_ENV=production npm install
2. clean them up with https://github.com/inikulin/dmn
3. commit them

Of course, the less dependencies and files, the better :)

[silverwind]

Of course, we could also go the route of requiring the user to install the dependencies if these guides are not part of the release build.

[Fishrock123]

I'm inclined to prefer not having them checked in, so long as the website build is able to work with that.

[Qard]

I think we can actually leave YAML parsing out of this entirely for now. It's mainly for eventually replacing the reference doctool that we want YAML frontmatter for. We can get to that later though. For now, we just want something that can build only the guide files in a way that it can be delivered with each release build to the website.

[jasnell]

What's the status on this one?

[Qard]

@kahwee Are you able to continue working on this? I can volunteer some time next week to help get this ready to merge, if you aren't able to get it finished up yourself.

[eljefedelrodeodeljefe]

@Qard will you find some time to pick this up? I guess it's blocking a lot of new doc stuff. Also we would need to continue discussion where guids will go on the website afterwards, right? cc @nodejs/documentation

[Qard]

I'll see what I can do. I don't have a ton of time available at the moment though, so I'd appreciate any help I can get. If other docs people could review this PR and see if they can put together any of the other modules we might need, that'd be a big help.

[eljefedelrodeodeljefe]

Alright. No pressure. I think I got some time tomorrow.

[eljefedelrodeodeljefe]

Okay I have picked this up.
If nobody objects I am gonna close this, for a couple of reasons:

• adding remark as dependency might not be necessary and is unwanted from what I hear.
• the doctool needed general refactoring to make this integrateable easily without using remark
• I am conducting refactoring here: doc, tools: refactor html generation  #6974 and will pick this here up directly afterwards