MDX v2 support

[jgarrow]

Description

1. Changed the a tag in the createContactInfo markdown function to follow the markdown link syntax of [text](url).
2. Removed the mdx-code-block code blocks in the markdown templates for the generateApiDocs function.
3. Added a new line before and after every tag in the create markdown util function.

Motivation and Context

I am upgrading my Docusaurus site to use MDX v2 and Code Hike and ran into several errors associated with the changes that this PR makes.

1. Without adding a new line before and after every tag in the create function, I get an error like this when spinning up the development server:

# Lots of these errors
Expected a closing tag for `<div>` (16:686-16:691) before the end of `paragraph`

# And then lots of these errors
[webpack.cache.PackFileCacheStrategy] Skipped not serializable cache item 'Compilation/modules|/Users/janessa.garrow/dev/openapi-docusaurus/node_modules/babel-loader/lib/index.js??ruleSet[1].rules[8].use[0]!/Users/janessa.garrow/dev/openapi-docusaurus/node_modules/docusaurus-mdx-loader-v2/lib/index.js??ruleSet[1].rules[8].use[1]!/Users/janessa.garrow/dev/openapi-docusaurus/node_modules/@docusaurus/plugin-content-docs/lib/markdown/index.js??ruleSet[1].rules[8].use[2]!/Users/janessa.garrow/dev/openapi-docusaurus/docs/platform-api/aggregate-member.api.mdx': No serializer registered for VFileMessage
<w> while serializing webpack/lib/cache/PackFileCacheStrategy.PackContentItems -> webpack/lib/NormalModule -> webpack/lib/ModuleBuildError -> VFileMessage

2. After updating the create markdown util to add a new line in between the tags, I ran into this error:

Error: Unknown language: mdx-code-block

Since the blocks flagged with mdx-code-block are just importing other components and using the JSX in the generated MDX files, I removed the code block syntax entirely and the components rendered as expected.

3. Finally, after making the above 2 changes, I get an error with the a tag in the contact info:

Expected a closing tag for `</a>` (54:1-54:7) before the end of `paragraph`

Changing that a tag to use markdown link syntax resolved the error.

How Has This Been Tested?

Screenshots (if appropriate)

Types of changes

• Bug fix (non-breaking change which fixes an issue)

Checklist

• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes if appropriate.
• All new and existing tests passed.

[welcome-to-palo-alto-networks]

🎉 Thanks for opening this pull request! We really appreciate contributors like you! 🙌

[github-actions]

Visit the preview URL for this PR (updated for commit 29b1322):

https://docusaurus-openapi-36b86--pr514-a1qsov89.web.app

_{(expires Thu, 20 Apr 2023 14:23:24 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

[sserrata]

Thanks for the PR @jgarrow! I was wondering if you might have a reproduction of the original issue available to clone somewhere? As I understand things, the root issue might result from interpolated HTML/MDX causing some broken tags but I am not familiar with MDX v2.0 or Code Hike.

Also, I noticed this in the deploy preview (not sure if it works in dev?):

[guitaoliu]

I am not sure if this is related. docusarus doesn't support MDX v2. facebook/docusaurus#8288

[sserrata]

Ok, I think I was able to reproduce some or all of what you encountered @jgarrow, by followed the docs here: https://codehike.org/docs/installation/docusaurus

Still debugging the errors but I'll use your changes in this PR as a guide.

[jgarrow]

@sserrata Here is the link to the project I'm currently working on. I spun up another one this morning that uses the install template from the docusaurus-plugin-openapi-docs docs.

I'm aware that Docusaurus doesn't currently support MDX v2, but you need to upgrade to it in order to use Code Hike.

• I noticed while making that second link I shared that Docusaurus has issues with it with the truncating syntax for blog posts since it relies on making a comment, which is handled different in MDX v2. I didn't notice that in my current project since I'm not using the blog feature.
• There is also an issue with that second example I shared where characters that are special characters in MDX v2 (such as <= or > comparison operators) and need to be escaped in the body. The issue here is that they shouldn't be escaped in the frontmatter, only in the body. See the frontmatter and first paragraph in this page.

[sserrata]

@jgarrow I think we're on the same page now although I reproduced on v2.3.1 and might be seeing something slightly different.

Here's what I am seeing:

Unexpected character `=` (U+003D) before name, expected a character that can start a name, such as a letter, `$`, or `_`
Expected a closing tag for `</a>` (241:1-241:7) before the end of `paragraph`

I think we could work toward escaping the comparison operators but replacing <a> tags with []() doesn't seem to work currently. I wonder if the markdown just needs to be on a separate line from the inline HTML.

[sserrata]

Yup, confirmed that this allows the markdown URL to render:

<span>

 URL: [https://github.com/Redocly/redoc](https://github.com/Redocly/redoc)

</span>

[jgarrow]

@sserrata I do know with MDX v2, any inline content inside of a JSX tag that would be turned into an inline HTML element will still be interpreted as markdown (see this section on their docs)

[jgarrow]

@sserrata Putting the span content in its own paragraph inserts a p tag inside of the span, which is a bit odd both semantically and with the bottom margin that the p tag brings

<span>

 URL: [https://github.com/Redocly/redoc](https://github.com/Redocly/redoc)

</span>

[sserrata]

We might need additional leading and trailing new lines to allow the markdown to render:

[jgarrow]

Yeah, MDX v1 will need it in order to render. MDX v2 knows how to handle it inline.

[sserrata]

Thanks @jgarrow - in your opinion, do you see a way for both MDXv1 and v2 to be supported with a common MDX output/format from this plugin?

[jgarrow]

@sserrata as much as I hate having a p tag inside of a span, this might be the only way to have it work with both MDX v1 and v2. Maybe we an add some inline styling to the span so that it removes the bottom margin from the child p tag that ends up wrapping around the text?

<span>

 URL: [https://github.com/Redocly/redoc](https://github.com/Redocly/redoc)

</span>

[Dr-Electron]

Just wanted to mention that afaik it is planned to support MDX 2 with Docusaurus 3.0, which should be the next release