Guides

[Murderlon]

As there has been talk of centralizing (some) of the docs and improving on helping users get started, I decided to start with writing more guides like the ones currently online and let those act as the introductory knowledge base about the ecosystem. These guides will probably get a prominent place on v2 of this website.

Any feedback is appreciated as well as ideas for new guides!

---

• [x] Introduction to unified

After reading this guide you will: understand what unified does, get a taste of the ecosystem., know how it can be used, know what parts (processors) you need for your (future) use case, have a list of resources to continue learning or get started.

• [x] Using unified

Learn how to use unified by transforming markdown to HTML. It’ll also show how to use plugins, add a table of contents, and check prose.

• [x] Create an online editor

Learn how to create an interactive online editor with unified. This guide creates a demo visualising syntactic properties of text.

• [ ] Setting up tooling for browser support.

Learn how to setup your favorite build tool to make unified usable in the browser.

• [ ] Introduction to syntax trees with unist, mdast, hast, and nlcst

As mentioned in https://github.com/syntax-tree/ideas/issues/7, this should not be writing yet another book on syntax trees, that largely duplicates existing resources. This guide should focus on getting a basic but sufficient mental model about syntax trees, how they're used in the ecosystem, and what specs like unist are.

• [ ] How to create a new syntax tree format

Learn how to make a proper specification for a content format.

• [x] How to get started with writing plugins

This guide goes deeper into how unified and processors work under the hood and explains some common approaches. Furthermore, it goes into the pros and cons of writing a plugin at parser level or, for instance, mdast.

• [ ] Writing a hast plugin

Walk through of an example plugin with hast.

• [ ] Writing a mdast plugin

Walk through of an example plugin with mdast.

• [ ] Writing as nlcst plugin

Walk through of an example plugin with nlcst.

• [ ] Writing a remark parser plugin.

Walk through of an example parser plugin .

• [ ] vfile?

Should probably be included but not sure how yet.

[ChristianMurphy]

Another possible guide series. Using Unified with:

• Rollup
• WebPack
• Angular CLI
• Create React App
• Vue CLI

See https://github.com/unifiedjs/unified/issues/34 for context

[wooorm]

Yeah that’s a great idea as well!

[wooorm]

This guide for Pandoc clearly explains some of the things we also need to explain: https://pandoc.org/filters.html

[wooorm]

Another idea: a guide on how to create a parser / syntax-tree format (spectrum)

[Murderlon]

Good one! I updated the issue to incorporate these new ideas.

[ChristianMurphy]

There is also a unified handbook now, is there any way these two efforts could be consolidated? /cc @johno

[Murderlon]

(accidentally closed the issue for a sec)

The to do list in it's current form mostly aligns with the intended contents of the handbook. But I'm not completely sure if the handbook should supersede all guides. I'd say it depends on how both would be presented.

Originally, I imagined the guides to live on V2 of the website with a title, subtitle, and reading time. They would be small and focused which would encourage users, who for instance just came to figure out what unified is about, to quickly and easily do just that. Instead of linking to a handbook GH readme with a scary table of contents with things like unist, abstract syntax trees, traversal, etc.

However, the handbook itself could be a readme and be presented on the website, structured and split up in way that makes sense for users, future plugin authors, and potential other areas.

---

• How do you (@unifiedjs/core) see the distinction between guides and the handbook?
• How would we link and present the centralized knowledge (either the handbook, guides, or both)?

[wooorm]

If anyone wants to restart work on this, I feel that the current set up makes it easier to work on them!

[januswel]

I searched docs to extends Markdown and found this

unified is really awesome but hard to use, because canonical documents for edge cases (like extending Markdown) are not available

But it seems this issue is not proceeding 🤔 Is it OK to send some PRs for the tasks? Or, users should refer the handbook?

[ChristianMurphy]

PRs enhancing and adding to the handbook are welcome!

[wooorm]

I looked at this issue again and wrote several guides! A lot has changed in 5 years too. Now that there are ±15 articles, I’d like to move towards separate issues for sections/articles that are missing.

• Setting up tooling for browser support

https://unifiedjs.com/learn/guide/unified-in-the-browser/

• Introduction to syntax trees with unist, mdast, hast, and nlcst

https://unifiedjs.com/learn/guide/introduction-to-syntax-trees/

• How to create a new syntax tree format

I didn’t write this; it doesn’t happen often. It first needs to happen before I can write about it

• Writing a hast plugin

https://unifiedjs.com/learn/guide/create-a-rehype-plugin/

• Writing a mdast plugin

https://unifiedjs.com/learn/guide/create-a-remark-plugin/

• Writing as nlcst plugin

This one existed for a while at https://unifiedjs.com/learn/guide/create-a-plugin/, I modernized it and moved it to https://unifiedjs.com/learn/guide/create-a-retext-plugin/

• Writing a remark parser plugin. (Walk through of an example parser plugin)

I didn’t write this; it would be like https://github.com/micromark/micromark#creating-a-micromark-extension; as this isn’t super recommended, I chose not to put it on the site

• vfile (Should probably be included but not sure how yet.)

I didn’t write this; vague, what it would be, indeed.