Add improved docs #900

wooorm · 2021-11-14T15:30:37Z

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

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

packages/remark-stringify/readme.md

packages/remark/readme.md

mgan59

👋🏻 I didn't have any blockers, but wanted to read through the changes and give some feedback an in general get caught up on the discussions happening here.

mgan59 · 2021-11-15T12:44:23Z

doc/plugins.md

 More plugins can be found on GitHub tagged with the
 [`remark-plugin` topic][topic].

-Have a good idea for a new plugin?
-See [Creating plugins][create] below.
+> 👉 **Note**: some plugins don’t work with recent versions of remark due to


I need to do an upgrade on my remark and need to audit which plugins are supported 💯 -- again I'm behind so not sure if this NOTE should also go in the root README?

A link here is already referenced in the migration guide: https://github.com/remarkjs/remark/releases/tag/13.0.0. That’s probably a better place for folks to find this point instead of buried somewhere in a big monorepo readme?

good point that folks are still upgrading though!

doc/plugins.md

packages/remark-cli/readme.md

packages/remark-parse/readme.md

packages/remark/readme.md

mgan59 · 2021-11-15T13:25:36Z

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.

Co-authored-by: Merlijn Vos <merlijn@soverin.net>

wooorm · 2021-11-15T18:06:11Z

@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.

packages/remark-cli/readme.md

Co-authored-by: Christian Murphy <christian.murphy.42@gmail.com>

…ark, just like gfm

readme.md

doc/plugins.md

Co-authored-by: Remco Haszing <remcohaszing@gmail.com>

packages/remark-cli/readme.md

packages/remark-cli/test.js

packages/remark-cli/readme.md

ChristianMurphy · 2021-11-18T14:13:46Z

readme.md

+remark is a very popular ecosystem of plugins that work with markdown as
+structured data, specifically ASTs (abstract syntax trees).
+ASTs make it easy for programs to deal with markdown.
+We call those programs plugins.
+Plugins inspect and change trees.
+You can use the many existing plugins or you can make your own.


Repeating back the keypoints in the order they appear:

remark is popular

remark is for markdown

remark uses ASTs

ASTs make it easy to edit markdown

Plugins can also edit things

There are a lot of plugins

Is that the order we want to present things?
Maybe:

remark is for markdown

remark uses ASTs and plugins

ASTs and plugins make editing easy

remark has a large community

community includes many remade plugins

?

I’m not sure what this would mean practically?
I don’t think remark really has a large community. I use popular here to mention that it is used a lot.

I don’t think remark really has a large community. I use popular here to mention that it is used a lot.

Adopters aren't part of the community?

Who do you mean by adopters?

Community to me sounds like folks actively interacting with repos, discussions, etc, and I don’t think we have much of that.

Adopters as in folks downloading and using remark, maybe opening an issue or a discussion, but not yet a maintainer.

So “user” in this chart, right?
There’s a divide there: folks that choose to put a markdown package in their package.json, and folks that use packages that somewhere include remark.
remark, compared to others, has few of those adopters/explicit users: https://github.com/remarkjs/remark/network/dependents?dependent_type=PACKAGE&package_id=UGFja2FnZS0xNDIzNzIzMw%3D%3D, https://github.com/markedjs/marked/network/dependents?dependent_type=PACKAGE&package_id=UGFja2FnZS0xMzQzNjIxNw%3D%3D, https://github.com/markdown-it/markdown-it/network/dependents?dependent_type=PACKAGE&package_id=UGFja2FnZS0xODE4NTUwMQ%3D%3D
But the most of implicit users, by download counts.
I don’t think it’s fair to say we have an exceptionally vibrant community here, but it is fair to say we’re the most popular.

but this is sort of besides the point of your earlier layout of a rewrite?

Add improved docs

4f68cff

wooorm added the 📚 area/docs This affects documentation label Nov 14, 2021

github-actions bot added 👋 phase/new Post is being triaged automatically 🤞 phase/open Post is being triaged manually and removed 👋 phase/new Post is being triaged automatically labels Nov 14, 2021

This comment has been minimized.

Sign in to view

Murderlon approved these changes Nov 15, 2021

View reviewed changes

packages/remark-stringify/readme.md Show resolved Hide resolved

packages/remark/readme.md Outdated Show resolved Hide resolved

wooorm added 2 commits November 15, 2021 13:28

Remove contents from getting-started.md

d784867

doc/plugins.md

433e27e

mgan59 reviewed Nov 15, 2021

View reviewed changes

Update packages/remark/readme.md

cc32bee

Co-authored-by: Merlijn Vos <merlijn@soverin.net>

wooorm added 7 commits November 15, 2021 19:06

Fix typo

1246d34

Improve link

211481f

Reword

af88e39

Reword some more

802462c

some more

f8bba89

Refactor

91f9a13

Add examples to remark

1e4974b

ChristianMurphy reviewed Nov 15, 2021

View reviewed changes

packages/remark-cli/readme.md Outdated Show resolved Hide resolved

wooorm added 8 commits November 15, 2021 20:16

Add example of config files

3556138

Remove superfluous phrase

587efb0

Format tip

4c96b75

Format note

a1cbda0

Reword

f7c80f0

Consistent casing

9efbd9d

Reword

4100319

Fix comments

7274e34

wooorm and others added 14 commits November 15, 2021 20:51

Reword

960781f

Try out different notes

ee8ddcc

Take two

55ff056

Update packages/remark-cli/readme.md

7d761e0

Co-authored-by: Christian Murphy <christian.murphy.42@gmail.com>

backport

895582f

Update descriptions in package.jsons

09cad33

tests

767b3ea

Reword

3d13de5

micromark

9a721ec

Add note on submitting security report

07ecfb7

lowlight some things

c8ca1b7

Remove unneeded alternative

2e3225a

Merge branch 'main' into docs

8d9046b

Mention remark-mdx, because mdx is also a good reason to choose rem…

a1084b5

…ark, just like gfm

remcohaszing reviewed Nov 17, 2021

View reviewed changes

readme.md Outdated Show resolved Hide resolved

doc/plugins.md Show resolved Hide resolved

doc/plugins.md Show resolved Hide resolved

doc/plugins.md Show resolved Hide resolved

wooorm and others added 2 commits November 18, 2021 09:42

Update readme.md

5969b6f

Co-authored-by: Remco Haszing <remcohaszing@gmail.com>

Add note on adding to the list of plugins

c9b2ad6

ChristianMurphy reviewed Nov 18, 2021

View reviewed changes

remcohaszing approved these changes Nov 18, 2021

View reviewed changes

package.json

beb9da8

ChristianMurphy approved these changes Nov 18, 2021

View reviewed changes

wooorm merged commit 87c50a5 into main Nov 18, 2021

wooorm deleted the docs branch November 18, 2021 18:14

wooorm added the 💪 phase/solved Post is done label Nov 18, 2021

This comment has been minimized.

Sign in to view

github-actions bot removed the 🤞 phase/open Post is being triaged manually label Nov 18, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add improved docs #900

Add improved docs #900

wooorm commented Nov 14, 2021 •

edited

This comment has been minimized.

This comment has been minimized.

mgan59 left a comment

mgan59 Nov 15, 2021

wooorm Nov 15, 2021

mgan59 commented Nov 15, 2021

wooorm commented Nov 15, 2021

ChristianMurphy Nov 18, 2021

wooorm Nov 18, 2021

ChristianMurphy Nov 18, 2021

wooorm Nov 18, 2021

ChristianMurphy Nov 18, 2021

wooorm Nov 18, 2021 •

edited

wooorm Nov 18, 2021

This comment has been minimized.

Add improved docs #900

Add improved docs #900

Conversation

wooorm commented Nov 14, 2021 • edited

Initial checklist

Description of changes

This comment has been minimized.

This comment has been minimized.

mgan59 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mgan59 commented Nov 15, 2021

wooorm commented Nov 15, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wooorm Nov 18, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment has been minimized.

wooorm commented Nov 14, 2021 •

edited

wooorm Nov 18, 2021 •

edited