Closed jakeboone02 closed 9 months ago
@tgreyuk , are you interested in PR's against master
, next
, next-dev
or neither at this point in the release cycle?
@jakeboone02 , it seems like MDX 2 is already planned to be part of the upcoming typedoc-plugin-markdown@4.0.0
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.
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 >
?
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.
@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.
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.
Closing as per comments. Thanks again for starting the conversation.
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 theglobals
property.