Support MDX v2

[jakeboone02]

This PR adjusts the output of typedoc-plugin-markdown to be compatible with MDX v2. Most of the changes are < → < and > → >.

In my limited testing, these changes maintain compatibility with MDX v1.

I wasn't able to get the tests to pass in this repo—which may be a setup issue on my machine—but I did get rid of the warning about configuring ts-jest via the globals property.

[birkskyum]

@tgreyuk , are you interested in PR's against master, next, next-dev or neither at this point in the release cycle?

[birkskyum]

@jakeboone02 , it seems like MDX 2 is already planned to be part of the upcoming typedoc-plugin-markdown@4.0.0

[jakeboone02]

Thanks @birkskyum. I'm wondering if they'll consider making the v3 branch compatible with MDX2 since v4 is kind of a big upgrade. The whole structure of the generated docs changes, some config options are different, etc.

[tgreyuk]

Apologies for the delayed response on this.

@birkskyum correct MDX 2 is the default for V4 and there are tests against it.

@jakeboone02 thanks for the initial PR. I have been looking at ways to accommodate this and although it appears an innocuous change I am reluctant to introduce this change in v3 and introduce unanticipated issues. I would recommend using v4 if MDX 2 support is required.

However I understand that as this is potentially a big step so as a compromise I have written a local plugin that should provide MDX2 support for v3 without changing the core plugin. Please see https://github.com/tgreyuk/typedoc-plugin-markdown-mdx2/blob/main/README.md. Have a play and let me know if it might work as a compromise for you.

On a side note I noticed that you went for html entity < rather than escaping the angle bracket with backslash \<. My preference is to use a backslash in this context (v4 backslash escapes opening and closing angle brackets) but i'd be interested for a counter reason to implement < and &gt ?

[jakeboone02]

Thanks for the response @tgreyuk. I think a plugin would be sufficient. I've patched the package locally in my repo so I don't strictly require a fix for the moment.

Actually when I submitted this PR I was unaware of v4, so I should have looked around more first.

The reason I went with HTML entities was I couldn't actually get the \< syntax to work. I'm using Docusaurus v3.0.0-beta.0 and MDX v2.3.0. When I use \<, I get a bunch of errors like this:

[ERROR] Client bundle compiled with errors therefore further build is impossible.
Error: MDX compilation failed for file "/path/to/react-querybuilder/website/api/interfaces/react_querybuilder.ActionProps.md"
Cause: Unexpected character `` ` `` (U+0060) before name, expected a character that can start a name, such as a letter, `$`, or `_`
Details:
{
  "name": "211:22",
  "message": "Unexpected character `` ` `` (U+0060) before name, expected a character that can start a name, such as a letter, `$`, or `_`",
  "reason": "Unexpected character `` ` `` (U+0060) before name, expected a character that can start a name, such as a letter, `$`, or `_`",
  "line": 211,
  "column": 22,
  "position": {
    "start": {
      "line": 211,
      "column": 22,
      "offset": 6206,
      "_index": 0,
      "_bufferIndex": 13
    },
    "end": {
      "line": null,
      "column": null
    }
  },
  "source": "micromark-extension-mdx-jsx",
  "ruleId": "unexpected-character"
}

When I use < and >, the site builds fine.

The PR in my repo that uses MDX 2 is here: react-querybuilder/react-querybuilder#537. My local patch for v3 (which is basically the same as this PR) is here.

FWIW I did try to upgrade to v4 but ran into the same problems.

[birkskyum]

https://mdxjs.com/blog/v3/

[jakeboone02]

@tgreyuk - One more thing about the HTML entity vs backslash escape: The Docusaurus v3 migration guide says that MDX v1 will render \< and \: as-is, not escaped like MDX v2+:

💡 HOW TO PREPARE

Available options to fix this error:

• Use inline code: Array<T>
• Use the HTML code: < or <
• Escape it: \< (unfortunately the \ will be displayed under MDX v1)

Seems like the HTML entity method is backwards compatible while the backslash escape method is not.

[tgreyuk]

The release of Docusaurus 3 has forced my hand on this so MDX2 is now supported in all versions. See https://github.com/tgreyuk/typedoc-plugin-markdown/issues/491.

[tgreyuk]

Closing as per comments. Thanks again for starting the conversation.