Update docs for newcomers #6
Conversation
github-actions
bot
added
👋 phase/new
This comment has been minimized.
This comment has been minimized.
|
@nemo-omen I’ve significantly reworked the docs some more. The rendered view is here: https://github.com/remarkjs/remark-directive/blob/docs/readme.md. The plan is to apply similar changes to all projects. |
| // This plugin is an example to let users write HTML with directives. | ||
| // It’s informative but rather useless. | ||
| // See below for others examples. | ||
| /** @type {import('unified').Plugin<[], import('mdast').Root>} */ |
There was a problem hiding this comment.
I'm not sure it JSDoc based type annotations should be used in examples. It's not wrong, but IMO it adds a bit of visual noise and doesn't really help to clarify the example.
There was a problem hiding this comment.
Maybe. It doesn’t hurt JS users who copy/paste (maybe a bit, as you mention, if it’s noisy).
It does boost the idea to both JS and TS users that types can come in plain JavaScript.
And it might signal to TS users how things can be typed, as they sometimes have a hard time typing unified plugins/utilities (using a lot of anys or unist.Node)?
But it’s less noisy than both JS and TS code blocks but is still copy/pastable compared to just TS code blocks.
| .use(myRemarkPlugin) | ||
| .use(remarkRehype) | ||
| .use(rehypeFormat) | ||
| .use(rehypeStringify) |
There was a problem hiding this comment.
Sometimes the order of plugins matters (transformers) and sometimes it doesn't (syntax extensions / custom parsers / compilers). I don't think it's necessary to document here, but it might be good to document for plugins that do depend on output of other plugins.
There was a problem hiding this comment.
Is it ever weird though? As in, do people come in thinking the order doesn’t matter?
There was a problem hiding this comment.
Not really. If anything it can be a bit surprising things work regardless of order, not the other way around.
This comment has been minimized.
This comment has been minimized.
wooorm
added
👶 semver/patch
Initial checklist
Description of changes
This improves the docs, focussing on newcomers.
The goal is to make it easier for folks without background information on unified/remark/asts/etc to figure out what a project is and if they need it or something else.
I thought I’d kick something off but the plan is for similar changes to go out to all unified readmes.
Related-to: unifiedjs/unified#168.
/cc @nemo-omen