Doctool: Remark plugins

[chrisdickinson]

This is a tracking issue for a new doctool using remark. The goals are:

• Render the api docs as HTML roughly equivalent to the existing doctool output.
• Render the guides and tutorials added to the nodejs/node repo as HTML.

This issue will contain all known breakages and necessary plugins (both existing and net new), broken into "required" and "nice to have":

Required

• @include syntax (remark-include by @Qard)
• Hook into Node Makefile
• YAML frontmatter (for stability index)
  • per-section YAML
• {Type} parsing (for parity with this PR)
• Basic layout selection (for switching between guides and API layouts)
• Header anchors

Nice to have

• Linting
  • ESLint for JS code examples
  • Link validation
  • API Method format validator
  • Make existing docs pass lint
  • Hook into Node Makefile tests
  • API headers — check to make sure they're in alphabetical order
• Switch table of contents generation to remark-toc

[Qard]

The current tool also handles the JSON output. So we'd need to be able to parse HTML comments for context data and identify traits of function signatures in headers.

I'm thinking it might actually be good to have something that can interpret YAML before any header to section metadata and just edit the docs to store the metadata it currently stores in a less bad way.

[chrisdickinson]

I'm thinking it might actually be good to have something that can interpret YAML before any header to section metadata and just edit the docs to store the metadata it currently stores in a less bad way.

I am 💯 in favor of this — are you thinking of something like:

### Some node header
<!--
stability: 0
added: v0.12.0
deprecated: v4.0.0
-->

[Qard]

Yes, that. We could put whatever arbitrary data into it and then add renderers to decide what to do with that data. 😊

[silverwind]

eslint-plugin-markdown might be a good fit to integrate into make jslint. markdownlint could be used for linting markdown itself, but I fear it might require another dotfile in the project root.

Edit: I see you're aiming for remark plugins, so if these can do the job, so be it. Still would be nice to have the CI go red on a linter violation 😉

[chrisdickinson]

@silverwind I think markdownlint would also add a dependency on Ruby, which might be a bit of a tough sell. It should be relatively straightforward to make a remark plugin that uses eslint, though!

[silverwind]

Oh, yeah, a Ruby dependency kills it.

Regarding linting both markdown and code in markdown, I was thinking about adding a doclint target to the Makefile/vcbuild, so one can lint without building the docs, which is kind of important, especially because there's no vcbuild doc for Windows yet.

[Qard]

I'm going to look into writing my own code block linter for this tonight or tomorrow night.

Also, 👍 for the doclint target. Should be easy enough to do. 😸

[Qard]

Cleaner anchor text?

[chrisdickinson]

@Qard User-defined anchors would be grand, though I don't mind just doing the hacky HTML thing, either:

<a id="human-defined-anchor"></a>

### Some section

An alternative I was poking around with was to create empty links and have a plugin pick 'em up:

### Some section [](#human-defined-anchor)

[Qard]

I wrote a thing for running eslint on fenced markdown code blocks.

Actually, I wrote it to plug into another thing I just wrote for running any kind of linter on fenced markdown code blocks.

Next up: a YAML metadata parsing thing.

[kahwee]

Where's the repo with the tool to generate the docs? I can try writing the plugins needed for them too.

[Qard]

The existing tool is in nodejs/node repo at tools/docs. The "new" tool doesn't exist yet, but I should hopefully have an in-progress PR up later today to start discussion.

I have so far been writing what I can as fully generic modules, and would like to keep it that way as much as possible.