This repository was archived by the owner on Mar 25, 2018. It is now read-only.
Repository navigation
This repository was archived by the owner on Mar 25, 2018. It is now read-only.
Doctool: Remark plugins #61
Description
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
-
@includesyntax (remark-includeby @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
Makefiletests - API headers — check to make sure they're in alphabetical order
- Switch table of contents generation to remark-toc
Activity
Qard commentedon Jan 20, 2016
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 commentedon Jan 20, 2016
I am 💯 in favor of this — are you thinking of something like:
Qard commentedon Jan 20, 2016
Yes, that. We could put whatever arbitrary data into it and then add renderers to decide what to do with that data. 😊
silverwind commentedon Jan 21, 2016
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
remarkplugins, 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 commentedon Jan 21, 2016
@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 commentedon Jan 21, 2016
Oh, yeah, a Ruby dependency kills it.
Regarding linting both markdown and code in markdown, I was thinking about adding a
doclinttarget to the Makefile/vcbuild, so one can lint without building the docs, which is kind of important, especially because there's novcbuild docfor Windows yet.Qard commentedon Jan 21, 2016
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 commentedon Jan 21, 2016
Cleaner anchor text?
chrisdickinson commentedon Jan 21, 2016
@Qard User-defined anchors would be grand, though I don't mind just doing the hacky HTML thing, either:
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 commentedon Jan 22, 2016
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 commentedon Jan 25, 2016
Where's the repo with the tool to generate the docs? I can try writing the plugins needed for them too.
Qard commentedon Jan 25, 2016
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.
Qard commentedon Feb 2, 2016
I'd like to discuss this in the call tomorrow. Specifically, how to achieve a project-focused build tool rather than single-file-focused and what the migration path for that would look like.
Trott commentedon Mar 13, 2018
Closing as this repository is dormant and likely to be archived soon. If this is still an issue, feel free to open it as an issue on the main node repository.