realworldocaml/mdx

support parts from more file formats

Opened this issue · 1 comments

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.

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.