Handle .mdx files

[nafg]

mdoc seems to be designed to work with Docusaurus, which uses MDX. Tools understand MDX better when the file extension is .mdx. Mdoc should process .mdx files the same way as .md files.

[kpodsiad]

@olafurpg I wonder if adding mdx to the https://github.com/scalameta/mdoc/blob/3078e6f13d9c808a3bcf106502b8082b0e639d45/cli/src/main/scala/mdoc/internal/cli/Settings.scala#L106 will be enough? As far I can tell it should allow to process mdx files but I've never seen mdoc codebase before and I'm not sure.

[tgodzik]

I think that should work, did you manage to test it out @kpodsiad ?

[kpodsiad]

It's not enough, .mdx file is just copied without resolving fenced code block.

[olafurpg]

Have you tried the flag —markdown-extensions=mdx? Everything in that settings file can be configured via the command line or sbt plugin

[baldram]

Everything in that settings file can be configured via the command line or sbt plugin

I tried and it worked, though it feels more like a workaround than a proper configuration.

I'm not sure how to configure these things from the SBT plugin level, since markdownExtensions is in the mdoc.internal.cli package. But I managed to hack it like this:

mdocExtraArguments ++= Seq("--markdown-extensions", "mdx", "--markdown-extensions", "md", "--markdown-extensions", "html")

(I had to repeat markdown-extensions multiple times because I couldn't set it once for all as md,mdx,html).

It seems to me that mdx should just be permanently added; it shouldn't be an option, because from Docusaurus version 2 (and we're now on version 3), it has built-in support for MDX, and that's a standard thing.

Putting aside the fact that Docusaurus has moved ahead of Mdoc (which by default supports Docusaurus v1 only), it's worth considering supporting the latest version. Even from version 2, it offers several key benefits, like more customization options and better UX. They are essential for modern-looking, clear and easy-to-read documentation.

And generally, not many changes are needed. I'm currently using Mdoc with Docusaurus 3 (but without using the DocusaurusPlugin to avoid hacks and workarounds).

To sum up, I tested it and everything works 😄 Just takes a bit of stubbornness and perseverance.