Add improved docs

[wooorm]

Initial checklist

• [x] I read the support docs
• [x] I read the contributing guide
• [x] I agree to follow the code of conduct
• [x] I searched issues and couldn’t find anything (or linked relevant results below)
• [x] If applicable, I’ve added docs and tests

Description of changes

• View monorepo readme
• remark-parse
• remark-stringify
• remark itself
• remark-cli
• doc/plugins

Questions and to-be-discussed:

• what to do with docs/ folder
• More examples? Less examples?

Related-to: unifiedjs/unified#168.

/cc @nemo-omen @remcohaszing @ChristianMurphy @Murderlon @with-heart @joostdecock @mgan59

[codecov-commenter]

Codecov Report

Merging #900 (beb9da8) into main (941baa4) will not change coverage. The diff coverage is 100.00%.

@@            Coverage Diff            @@
##              main      #900   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           10        10           
  Lines          905       905           
=========================================
  Hits           905       905           

Impacted Files	Coverage Δ
packages/remark-cli/test.js	100.00% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 941baa4...beb9da8. Read the comment docs.

[github-actions[bot]]

Hi! It seems some of the things asked in the template are missing? Please edit your post to fill out everything.

• [x] Initial checklist
• [ ] Description of changes (todo)

You won’t get any more notifications from me, but I’ll keep on updating this comment, and remove it when done!

If you need it, here’s the original template

```markdown ### Initial checklist * [ ] I read the support docs * [ ] I read the contributing guide * [ ] I agree to follow the code of conduct * [ ] I searched issues and couldn’t find anything (or linked relevant results below) * [ ] If applicable, I’ve added docs and tests ### Description of changes TODO ```

Thanks, — bb

[mgan59]

Few additional thoughts about open-questions

What to do with docs/ folder

I'd say keep it and continue to place documents in there that are meant for the larger mono-remark repo. Have you considered starting any kind of ADR/RFC process around the various sub-packages? Could also be a place to put larger tutorials / examples that use the various packages.

More examples, less examples?

I think it is always good to have 1-2 examples in the Readme for the package. Can always link from that section to followup/inter-related markdown documents in the root docs/ folder that are more involved examples organized by function/role. Whether that is advanced plugin development, building testing / tooling workflows, etc. An example here is part of my processing pipeline requires me to use remark-cli to generate test-fixtures since we do contract-driven test-development.

[wooorm]

@mgan59 Thanks for the review! I particularly appreciate opinions on these docs from folks that don’t actively maintain them, it’s helpful to hear what is hard, what you didn’t know before, and what’s vague!

Could also be a place to put larger tutorials / examples that use the various packages.

in most cases I think those can go on unifiedjs.com: one place to collect the overarching docs.

Have you considered starting any kind of ADR/RFC process around the various sub-packages

We do have unifiedjs/rfcs, but it’s not very active. Also a lot of processes are described here in unifiedjs/collective.

[github-actions[bot]]

Hi! This was closed. Team: If this was merged, please describe when this is likely to be released. Otherwise, please add one of the no/* labels.