Conduct survey of OMD users

[shonfeder]

In order to inform our development and prioritization of features, should we conduct a survey to solicit input from users?

Useful information might include:

• How many users are there (there are only 12 packages using omd on opam, how many uses outside of opam?)
• How is omd primarily used currently? (Just to generate html? Consuming the AST? How many people use the parsing extension facilities from omd 1?)
• What features are most desired by users? (Location info, syntax extensions, other target formats, etc.)
• What are the biggest complaints/short coming about the current state of the library (if any?).

[jfrolich]

I am exploring to use omd in the ReasonML parser/printer to allow for inline markdown documentation (instead of ocamldoc), and converting it to ocamldoc in the parser. I started this quite a while ago, and hope to come back to it when time allows :) The conversion from markdown to ocamldoc is already finished. The next step that is open is to include it in the parser in a proper way.

This is also why I would love to see markdown->markdown in this package. Basically printing markdown to a standardized output with a fixed line-width (just like prettier does at the moment).

I'm pretty sure that I will start using this library soon to perform markdown transformations. I imagine that I will read a markdown file, run snippets through some ocaml evaluation, generate table of contents, and then output back to markdown. After that, I am hoping that another process will read the generated markdown and convert it to html, using rehype-react (inside of javascript).

What would be amazing is if I could intertwine AST transformations in unifiedjs with ocaml transformations using omd and both projects used the same serialized AST.

[ulugbekna]

OCaml-LSP vendors OMD v1. The primary use we have is to translate OMD's markdown AST to a string using Omd.to_markdown : Omd.element list -> string. We thus format code comments on hover.

[jfrolich]

@ulugbekna: I see that ocaml-lsp has a ocamldoc to markdown converter. I implemented the opposite (markdown to ocamldoc, see #215). @shonfeder, would that be something you would consider including in omd. A use-case for converting md to ocamldoc is to include standalone markdown files in the odoc documentation (is more friendly as readable format on github). The opposite is apparently used in ocaml-lsp.

And there are more use-cases. In line with the mission of ReasonML to provide a more familiar syntax, it would also make sense to have markdown syntax in doc comments.

[shonfeder]

Thanks for the feedback, all! We hope to send out a more formal survey this quarter, but this feedback is a big help!

[shonfeder]

@Kanishka-work

What would be amazing is if I could intertwine AST transformations in unifiedjs with ocaml transformations using omd and both projects used the same serialized AST.

I think we'd want to learn more to motivate this. Feel free to open an issue that explains why we'd want to target unifiedjs in particular (as opposed to say Pandoc's AST, or any number of other formats we might target.).

[shonfeder]

@jfrolich Are you asking about adding support for ocamldoc -> html or following up on your (long) pending PR?

I think we'd want to learn more to motivate this.

I haven't used all the command line and browser based markdown transformers, so you would know better here.

It is very common to transform markdown to html (and use dangerously set html) or ReactJS elements (and interleave the elements with the rest of a reactjs page) in static site generators like eleventy, gatsby, and nextjs. They typically use a library like mdxjs (remark) to perform the transformation at site build time, running in a node environment. Since a lot of the world that works with markdown consists of people building static sites on top of nodejs, using a popular library in the npm universe would connect with that world. But things might change. Years ago jekyll was king and the markdown processing was happening in ruby...

I wouldn't target pandoc, since it's trying to provide a lowest common denominator interchange format, rather than model all the details of markdown.

The distinction between mdast and hast sounds useful, if you decide to adopt the remark approach.

[shonfeder]

@Kanishka-work, that's a good point re: the targeted use-case of Pandoc. I think @sonologico has hit on a nice solution, which parameterizes over element attributes to provide a simple AST with room for arbitrary complexity in associated meta-data.

It is very common to transform markdown to html (and use dangerously set html) or ReactJS elements (and interleave the elements with the rest of a reactjs page) in static site generators like eleventy, gatsby, and nextjs

Omd already transforms markdown to html, and can be used as part of a static site generator (indeed, there are several static site generators that depend on Omd already).

They typically use a library like mdxjs (remark) to perform the transformation at site build time, running in a node environment. Since a lot of the world that works with markdown consists of people building static sites on top of nodejs, using a popular library in the npm universe would connect with that world. But things might change.

ito support for nodejs static sites, I don't know why someone already using nodejs would want to add a dependency on an ocaml library for handling markdown. Do you have a thought on that?

In any case, it looks to me like it should be pretty straightforward to map the Omd AST to mdast as a serialization target. If there was a concrete use case presented indicating a clear need for this from Omd directly, we could open an issue to discuss the tradeoffs of adding it to this package. Otherwise, i think it should be pretty straight forward to write a simple transformer library that depends on this one.

I don't know why someone already using nodejs would want to add a dependency on an ocaml library for handling markdown

Yes, this will be very rare. The only cases where I could see this happening is someone wanting to use ocaml-mdx, or if someone preferred an omd based code highlighter over highlight.js

I also realized that people can use rehype-parse to integrate omd with remark/rehype.

Another wishlist item would be a small site like the following, where I could search future plugins/addons that are available for OMD:

https://unifiedjs.com/explore/