realworldocaml / mdx

Execute code blocks inside your documentation
ISC License
269 stars 45 forks source link

support parts from more file formats #402

Open dwang20151005 opened 2 years ago

dwang20151005 commented 2 years ago

Hi, may I contribute a PR to add support for quoting parts from file formats other than ocaml and shell?

We internally use mdx to write documentation, some of which benefits from quoting other file types. I sometimes work around this by using other preprocessors (e.g., cinaps) to generate both the mdx and the source file. But also I sometimes try to keep docs up to date manually instead, and then they get stale and users are confused. :-(

Anyway, I have a working implementation which adds support for several common file types, based on the file name extension:

| "c" | "cpp" | "h" | "hpp" | "java" | "js" -> Some slash_star_and_star_slash
| "hs" -> Some double_dash_and_nothing
| "html" | "md" | "mdx" -> Some html_style
| "org" | "py" | "sh" | "t" -> Some hash_and_nothing

It allows the user to specify additional comment syntaxes in-line by adding comment-begin and (optionally) comment-end attributes. E.g.,

<!-- $MDX file=./foo.bat,part=part1,comment-begin=REM -->
<!-- $MDX file=./foo.clj,part=part1,comment-begin=(comment,comment-end=) -->

Limitations:

  1. MDX part delimiters must be single-line comments that take up a whole line (modulo whitespace), even when the underlying syntax supports multiline comments and mixed code/comment lines.

    (This might be fixed by #374 / #387 . I was experimenting with an older vendored copy and haven't rebased yet.)

  2. Comment-begin and comment-end values may not include commas.

These are not fundamental, only consequences of existing implementation details in the parsing code.

Happy to rebase and submit a PR if this sounds in principle like a change you would accept.

askvortsov1 commented 1 year ago

As a fellow MDX user, this would be pretty cool! For my use case, it would be nice to insert content from other .md and .mdx files as block quotes.