[documentation] `remark-stringify` readme needs a simple example of rendering a tree into md

[revelt]

Subject of the issue

Hi all! Thank you for creating and maintaining these packages. I want to kindly complain about remark-stringify documentation.

remark-stringify readme is not beginner-friendly. We should add a simple example of code where we take a piece of markdown as string, parse it into tree and assign that tree into a variable. Then, take that tree and render it into a markdown again:

const tree = unified()
    .use(markdown)
    .parse("# Hello world!");
  console.log(
    `tree = ${JSON.stringify(
      tree,
      null,
      4
    )}`
  );

  // how do we stick the "tree" into this pipeline and render a string of markdown file again?
  const doc = unified().use(stringify);
  console.log(
    `doc = ${JSON.stringify(doc, null, 4)}`
  );

PS. I'm not seeking to render HTML, just parse and render again the same markdown.

We should add the above example (just fixed) into remark-stringify readme (https://github.com/remarkjs/remark/blob/master/packages/remark-stringify/readme.md).

Thank you.

[ChristianMurphy]

@revelt the documentation you are looking for is here: https://github.com/unifiedjs/unified#description

[revelt]

thanks @ChristianMurphy! I trawled the unit tests in remark-stringify and found it eventually. For posterity, simple parse-and-render scenario looks like this (in ES Modules, but if you can just replace import with require to get CommonJS):

import unified from "unified";
import markdown from "remark-parse";
import stringify from "remark-stringify";

const tree = unified()
  .use(markdown)
  .parse("# Some title");

console.log(`tree = ${JSON.stringify(tree, null, 4)}`);

const doc = unified()
  .use(stringify)
  .stringify(tree);

console.log(`${`\u001b[${33}m${`doc`}\u001b[${39}m`} = ${doc}`);

I'll fork and raise a PR for that readme.

[wooorm]

Hi! What are you doing? Why do you need access to the tree?

[revelt]

hi @wooorm! I'm very impressed with your work. I'm trying to write a quick app which would remove dud entries from changelogs, generated by lerna + conventional changelogs setup. In particular, documentation patches generate useless entries and I want to delete them from bunch of changelogs. For example, these two would go:

## [2.9.5](https://bitbucket.org/codsen/codsen/src/master/packages/ranges-apply/compare/ranges-apply@2.9.4...ranges-apply@2.9.5) (2019-01-01)

**Note:** Version bump only for package ranges-apply

## [2.9.4](https://bitbucket.org/codsen/codsen/src/master/packages/ranges-apply/compare/ranges-apply@2.9.3...ranges-apply@2.9.4) (2018-12-29)

**Note:** Version bump only for package ranges-apply

Now, it also happens that sometimes commit "spills" into many changelogs and I want to delete certain entry from all changelogs, then, if needed, also clean up the blank titles as well.

For this, I want to code up a string-in, string-out npm library (which could be tapped later by CLI or web app GUI). The library would essentially be a function which would:

• parse the changelog,
• manually locate and delete the AST nodes that contain "**Note:** Version bump only", OR optionally, whatever string with wildcards user provided (traverse AST and match using matcher).
• In either case, after traversal, clean up empty AST branches, deleting now empty changelog entry titles.

I wrote an AST traversal library (ast-monkey-traverse) and know how to use object-path so it should be doable.

If you feel there is a more efficient way than manually deleting nodes from AST, please share the ideas. I'm sure I'm doing not the most cleanest or the most efficient way.

[wooorm]

This is what plugins are for! And sure, you could create your own library wrapping unified to expose a different API. But now you’re writing your own parse/transform/stringify steps. That’s exactly what unified already does. Don’t, embrace the interface instead and create a plugin!

Have you read the documentation? There are some very helpful guides already.

[revelt]

@wooorm OK. I'll try. Thank you for guidance.