search

scalameta / mdoc

Typechecked markdown documentation for Scala
https://scalameta.org/mdoc/
Apache License 2.0
396 stars 81 forks source link

Handle .mdx files #604

Open nafg opened 2 years ago

nafg commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

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

kpodsiad commented 2 years ago

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

olafurpg commented 2 years ago

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

baldram commented 9 months ago

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.