Exposes the independent steps into individual functions #27
Conversation
arcanis
changed the title
|
I updated the PR to use a different approach which I found more flexible in my fork. |
|
We could go this way, temporarily, before we support plugins. I’m not opposed to utilities. That you as a somewhat advanced developer can mix and match together. |
I suppose the problem then becomes the opposite: what about people who don't want the compile function to be async 😄 That said, I don't mind if there's also a plugin API - I just find it convenient to have the primitives available. More power to advanced developers, as you said! |
|
In the JS world, plugins can return promises or not, and based on that, if a promise is returned but I’m not sure how this would work exactly in Rust, but we could also have both At least in the JS world, with promises, await, and top-level await, it’s much easier to use async stuff, and there aren‘t many reasons anymore to use sync stuff. |
| /// | ||
| /// ## Errors | ||
| /// | ||
| /// This project errors for many different reasons, such as syntax errors in | ||
| /// the MDX format or misconfiguration. | ||
| pub fn compile(value: &str, options: &Options) -> Result<String, String> { | ||
| pub fn parse_to_mdast(value: &str, options: &Options) -> Result<mdast::Node, String> { |
There was a problem hiding this comment.
I’d prefer reusing the names that are currently used in the JS world, albeit that this one is specific to MDX instead of markdown, which doesn’t exist there.
How about mdast_util_from_mdx, inspired by mdast-util-from-markdown
| /// This project errors for many different reasons, such as syntax errors in | ||
| /// the MDX format or misconfiguration. | ||
| pub fn mdast_to_hast(mdast: &mdast::Node) -> hast::Node { | ||
| mdast_util_to_hast(mdast) |
There was a problem hiding this comment.
I think this should be exposed as the full name: mdast_util_to_hast.
| /// | ||
| /// This project errors for many different reasons, such as syntax errors in | ||
| /// the MDX format or misconfiguration. | ||
| pub fn hast_to_program( |
| /// the MDX format or misconfiguration. | ||
| pub fn hast_to_program( | ||
| hast: &hast::Node, | ||
| original_source: &str, |
There was a problem hiding this comment.
I think this should match value from earlier
| Ok(program) | ||
| } | ||
|
|
||
| pub fn program_to_string(program: &mut Program) -> String { |
I'd like to access the original AST in order to extract the frontmatter data plus a couple of other information (like the headers, to generate a page navigation), but it wasn't possible before without parsing the file twice - possibly with different parsing options if I'm not careful. Additionally, I wanted to perform a couple of hast modifications before turning the tree into JS (in order to add heading anchors), but it wasn't exposed at all (neither on mdxjs-rs nor markdown-rs).
This diff solves that by splitting the various transforms into separate functions that the library consumer may call on their own. The crate still exports the "high-level"
compilemethod, but by calling the steps manually one has much better control over the various trees.It supercedes #8, since it makes it trivial to apply mutations to the trees before calling the next step (and I think it's better this way, because it becomes possible to perform async mutations, which wasn't possible with the callback approach in #8).