docusaurus

docusaurus copied to clipboard

Work in progress

---

Review links:

• https://deploy-preview-8288--docusaurus-2.netlify.app/tests/pages/markdownPageTests/#admonitions
• https://deploy-preview-8288--docusaurus-2.netlify.app/docs/markdown-features/admonitions/

---

Relevant links:

• https://github.com/facebook/docusaurus/issues/4029
• https://github.com/pomber/docusaurus-mdx-2
• https://mdxjs.com/blog/v2/
• https://mdxjs.com/migrating/v2/
• https://github.com/pomber/mdx-debugger
• https://jestjs.io/docs/ecmascript-modules

Breaking changes

Public API breaking changes:

Notable private API changes:

• mdx-loader requires the options.markdownConfig to be provided (see also https://github.com/facebook/docusaurus/pull/8419)

TODO

Complete this breaking changes PR: https://github.com/facebook/docusaurus/pull/8058

✅ [V2]

Name	Link
🔨 Latest commit	5ab8e86f30a5b004f139705a53b0a78de4a47f44
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/6442c74c8c23ef0008b98b54
😎 Deploy Preview	https://deploy-preview-8288--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 82	🟢 97	🟢 92	🟢 100	🟢 90	Report
/docs/installation	🟠 76	🟢 100	🟢 92	🟢 100	🟢 90	Report

Size Change: +148 B (0%)

Total Size: 1.01 MB

Filename	Size	Change
website/build/assets/css/styles.********.css	113 kB	+36 B (0%)
website/build/assets/js/main.********.js	752 kB	+112 B (0%)

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	101 kB
website/build/index.html	41.3 kB

_{compressed-size-action}

Note the docs says:

Unescaped left angle bracket / less than (<) and left curly brace ({) have to be escaped: < or { (or use expressions: {'<'}, {'{'})

https://mdxjs.com/docs/what-is-mdx/

Problem - Heading anchor syntax {#anchor-id}

MDX 2 interprets { as the start of an expression and it should be escaped to \{ in our case.

https://mdxjs.com/docs/troubleshooting-mdx/#could-not-parse-importexports-with-acorn-error

Solution: escape the md files with regexp for retrocompatibility and convenience (https://github.com/facebook/docusaurus/pull/8288/commits/83064b22970dc0cfe55d9568f02d73724eeeb17b)

It's not possible to implement this as a remark plugin (too late in the process)

We probably don't want to ask users to do such escaping, nor change our existing syntax.

Note the React beta site have the same feature with a different syntax: https://github.com/reactjs/reactjs.org/blob/main/beta/src/content/index.md

## What is this site? {/*what-is-this-site*/}

---

Problem - <!-- HTML comments

The < lead to a similar acorn error and need to be escaped.

Note: it only happens with format: "mdx", not 'md', and we may allow users to use the md format (through frontmatter) for improved compatibility and easy migration to Docusaurus.

Solution? A quick prepressing that escapes all HTML comments

---

Problem - // js comments in JS

This code in MDX doesn't work anymore due to the JS comment:

import LiteYouTubeEmbed from 'react-lite-youtube-embed';

<div className="video-container">
  <LiteYouTubeEmbed
    // cSpell:ignore Yhyx Sksg
    id="Yhyx7otSksg"
    params="autoplay=1&autohide=1&showinfo=0&rel=0"
    title="Docusaurus: Documentation Made Easy"
    poster="maxresdefault"
    webp
  />
</div>

Unexpected character / (U+002F) after self-closing slash, expected > to end the tag (note: JS comments in JSX tags are not supported in MDX

Solution? Remove the comment?

---

Problem - Math equations

$$
I = \int_0^{2\pi} \sin(x)\,dx
$$

Could not parse expression with acorn: Expecting Unicode escape sequence \uXXXX

Solution: again, escape \{ ?

$$
I = \int_0^\{2\pi} \sin(x)\,dx
$$

Hi, stumbled on this while investigating some errors I had (which are unrelated, but I found some stuff which might be useful)

In this file, this line will not work anymore, as the export has been removed. I naively replaced the line with const mdx = React.createElement and it worked (in the scenario I was dealing with). Thought it might be useful for you, if you weren't already aware.

Thanks for your work, and good luck with the migration!

I've been watching this PR for months because months ago I needed some MDX2 features to make some plugins work or something along those lines. Congrats and thank you for merging this! 🥳

Struggling to upgrade your site to MDX v2?

Here's a discussion to ask for support: https://github.com/facebook/docusaurus/discussions/9053

Just linking in a related issue here: https://github.com/facebook/docusaurus/issues/9081#issuecomment-1601350219

I'd love to see a guide on how to migrate remark / rehype plugins to Docusaurus v3 / MDX v2

I documented this a bit better already for v3, but due to Crowdin issues our website refuse to deploy for a long time... 😓

It sounds like the docs may exist - but not yet be visible!