v3 release

[gabrielcsapo]

👋 just a question on where we can track progress on react@18 and mdx@2.

Seeing if anyone can jump in to push those to things forward.

[slorber]

I'm working on MDX 2 every week here: #8288

Unfortunately, it's not a simple task and there are various implications to consider to help the community upgrade without too much pain.

Not sure it would be simple to onboard someone to help me, apart maybe testing the alpha once ready.

[gabrielcsapo]

we have 50+ sites running docusaurus internally, more than happy to test the beta and see what we run into.

[julrich]

Also very happy to beta test, when the time comes :)

[limaAniceto]

Happy to help test the alpha 👍

Feel free to tag me when you want to

[arobbins]

Happy to test anything as well.

[YOU54F]

Count me in for alpha testing over at https://github.com/pact-foundation and on personal sites

[slorber]

• The MDX 2 PR has been merged
• I documented many breaking changes and provided some compatibility options
• A canary release is now available (>= 0.0.0-5556)

Please test it and give me some feedback here! 🙏

cc @gabrielcsapo @julrich @limaAniceto @arobbins @YOU54F

[slorber]

@YOU54F your page website/docs/users/trustedby.mdx looks very suspicious to me.

---
title: Trusted by
---

Pact is proud to be in use and protecting deployments for the following companies and more

import Layout from '@theme/Layout';
import { MarkdownBlock } from '../../src/components/CompLibraryV2';
const users = require('../../src/data/users.json')
const repoUrl = "https://github.com/pact-foundation/docs.pact.io"
const editUrl = `${repoUrl}/edit/master/website/docusaurus.config.js`;
const showcase = () => {
const chunkSize = 3;
const renderList = []
for (let i = 0; i < users.length; i += chunkSize) {
  const chunk = users.slice(i, i + chunkSize);
  renderList.push(<tr key={'logorow-'+i}>{chunk.map((user) => {
    return (
        <td key={user.caption}>
          <a href={user.infoLink} key={user.caption}>
            <img src={user.image} alt={user.caption} title={user.caption} width='150'></img>
          </a>
        </td>
    );
  })}</tr>)
}
return renderList
}

<div className="logos"><table><tbody>{showcase()}</tbody></table></div>

This is not supposed to work with either MDX v1 or v2:

• MDX v1 playground
• MDX v2 playground

---

There were two errors, one with Remarkable, but replaced almost drop-in with Markdown-It.

I don't know what error you mean here, so can't help figure this out. Remarkable is not part of Docusaurus v2 which does not have a "CompLibrary" anymore. This comes from Docusaurus v1 so we can't really support things in v3 that we already deprecated in v2 😅
https://v1.docusaurus.io/docs/en/api-pages#complibrarymarkdownblock

---

Thanks for giving mdx 2 a try

In general that would be helpful if you could produce a smaller repro of the problem you are facing using MDX v2.

It's hard and time consuming for me to navigate your site, identify precisely a problematic page, find the relevant mdx file and figure out what could be the problem. And I might lose time for no good reason because the problem can be related to your own setup and site customizations.

I'd appreciate if you could create a new discussion entry per problem, and provide a small repro + mention of which page URL/path and which mdx file in that repro I'm supposed to look at.

If you say "there are problems related to images" it's a bit vague and makes me lose some precious time.

[slorber]

@slorber is the CommonMark parser used for .md file supposed to support HTML tags in MD documents? On latest canary, HTML tags seems to be simply stripped out completely. Not sure if this is intended behavior, but it makes migrating MD documents from other sources not straightforward.

Let's take @YOU54F case:

• This page (mdx v1) has images/videos: https://docs.pact.io/
• This page (mdx v2) has no images/videos: https://deploy-preview-255--docs-pact-io.netlify.app/
• Source file: website/docs/getting_started.md

You will notice that the source file is using .md (and not .mdx).

Under MDX v2 means that:

• this page has no ability to use embedded JSX components
• this page will use CommonMark and eventually allow sanitized HTML tags
• this page used to use JSX and now uses CommonMark due to the file extension: this can have unwanted side-effects

To ensure you still use MDX, you can use the .mdx extension. It is preferable to use the right extension particularly if you use MDX features (ie JSX/React/imports/exports).

We also have this front matter that can opt-in for MDX parsing while still using a .md extension: format: mdx

If you want to stick to CommonMark, that parser is much more fail-safe and won't report a lot of compilation errors.

As far as I know, this CommonMark mode will sanitize the md input to prevent security issues. Not too surprised to see some tags being removed. We probably need some options like these: https://github.com/remarkjs/remark-rehype#example-supporting-html-in-markdown-na%C3%AFvely

[slorber]

Let's track this problem here: #8960

couldn't make it work yet

[YOU54F]

sorry @slorber i didn't have time to provide a full review so felt some commentary was better than none. The site has some heritage code shall we shall that i am happy to remove/replace with more suitable options.

thank you for your time, patience and efforts as always

[slorber]

FYI the PR above has been merged

[slorber]

Both React 18 and MDX 2 PR have been merged, so you can try them in a canary release. I'll release the first alphas very soon.

For MDX v2 upgrade support, see #9053