[pull] main from facebook:main

packages/create-docusaurus/templates/shared/blog/2019-05-28-first-blog-post.md → packages/create-docusaurus/templates/shared/blog/2019-05-28-first-blog-post.mdx

@@ -7,6 +7,6 @@ tags: [hola, docusaurus]
 
 Lorem ipsum dolor sit amet...
 
-<!-- truncate -->
+{/* truncate */}
 
 ...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet

packages/create-docusaurus/templates/shared/blog/2019-05-29-long-blog-post.md → packages/create-docusaurus/templates/shared/blog/2019-05-29-long-blog-post.mdx

@@ -7,9 +7,9 @@ tags: [hello, docusaurus]
 
 This is the summary of a very long blog post,
 
-Use a `<!--` `truncate` `-->` comment to limit blog post size in the list view.
+Use a `{/*` `truncate` `*/}` comment to limit blog post size in the list view.
 
-<!-- truncate -->
+{/* truncate */}
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
 

packages/create-docusaurus/templates/shared/blog/2021-08-26-welcome/index.md → packages/create-docusaurus/templates/shared/blog/2021-08-26-welcome/index.mdx

@@ -9,7 +9,7 @@ tags: [facebook, hello, docusaurus]
 
 Here are a few tips you might find useful.
 
-<!-- truncate -->
+{/* truncate */}
 
 Simply add Markdown files (or folders) to the `blog` directory.
 

packages/create-docusaurus/templates/shared/docs/tutorial-basics/congratulations.md → packages/create-docusaurus/templates/shared/docs/tutorial-basics/congratulations.mdx

@@ -8,7 +8,7 @@ You have just learned the **basics of Docusaurus** and made some changes to the
 
 Docusaurus has **much more to offer**!
 
-Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.
+Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.mdx)** and **[i18n](../tutorial-extras/translate-your-site.mdx)**.
 
 Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)
 

packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx

@@ -20,9 +20,25 @@ slug: /my-custom-url
 ---
 // highlight-end
 
-## Markdown heading
+Markdown content
+```
+
+## Headings {/* #my-heading-id */}
+
+Markdown headings are supported using the standard “#” syntax and are automatically added to the table of contents. The number of `#` corresponds to the heading level.
+
+```md
+## Headings
 
-Markdown text with [links](./hello.md)
+My text
+```
+
+### Heading Ids {/* #my-custom-id */}
+
+Add `{/* #my-custom-id */}` after the heading text to assign it an explicit anchor id, used for linking.
+
+```md
+### Heading Ids {/_ #my-custom-id _/}
 ```
 
 ## Links
@@ -34,10 +50,10 @@ Let's see how to [Create a page](/create-a-page).
 ```
 
 ```md
-Let's see how to [Create a page](./create-a-page.md).
+Let's see how to [Create a page](./create-a-page.mdx).
 ```
 
-**Result:** Let's see how to [Create a page](./create-a-page.md).
+**Result:** Let's see how to [Create a page](./create-a-page.mdx).
 
 ## Images
 
@@ -80,26 +96,26 @@ function HelloDocusaurus() {
 Docusaurus has a special syntax to create admonitions and callouts:
 
 ```md
-:::tip My tip
+:::tip[My tip]
 
 Use this awesome feature option
 
 :::
 
-:::danger Take care
+:::danger[Take care]
 
 This action is dangerous
 
 :::
 ```
 
-:::tip My tip
+:::tip[My tip]
 
 Use this awesome feature option
 
 :::
 
-:::danger Take care
+:::danger[Take care]
 
 This action is dangerous
 

packages/docusaurus-types/src/config.d.ts

@@ -41,6 +41,7 @@ export type FutureV4Config = {
   useCssCascadeLayers: boolean;
   siteStorageNamespacing: boolean;
   fasterByDefault: boolean;
+  mdx1CompatDisabledByDefault: boolean;
 };
 
 // VCS (Version Control System) info about a given change, e.g., a git commit.

packages/docusaurus-types/src/index.d.ts

@@ -21,6 +21,7 @@ export {
 } from './config';
 
 export {
+  MDX1CompatOptions,
   MarkdownConfig,
   MarkdownHooks,
   DefaultParseFrontMatter,

packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap

@@ -27,6 +27,7 @@ exports[`loadSiteConfig website with .cjs siteConfig 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -114,6 +115,7 @@ exports[`loadSiteConfig website with ts + js config 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -201,6 +203,7 @@ exports[`loadSiteConfig website with valid JS CJS config 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -288,6 +291,7 @@ exports[`loadSiteConfig website with valid JS ESM config 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -375,6 +379,7 @@ exports[`loadSiteConfig website with valid TypeScript CJS config 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -462,6 +467,7 @@ exports[`loadSiteConfig website with valid TypeScript ESM config 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -549,6 +555,7 @@ exports[`loadSiteConfig website with valid async config 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -638,6 +645,7 @@ exports[`loadSiteConfig website with valid async config creator function 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -727,6 +735,7 @@ exports[`loadSiteConfig website with valid config creator function 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -819,6 +828,7 @@ exports[`loadSiteConfig website with valid siteConfig 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,

packages/docusaurus/src/server/__tests__/__snapshots__/site.test.ts.snap

@@ -107,6 +107,7 @@ exports[`loadSite custom-i18n-site loads site 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -282,6 +283,7 @@ exports[`loadSite simple-site-with-baseUrl loads site - custom config 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -449,6 +451,7 @@ exports[`loadSite simple-site-with-baseUrl loads site - custom outDir 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -616,6 +619,7 @@ exports[`loadSite simple-site-with-baseUrl loads site 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -827,6 +831,7 @@ exports[`loadSite simple-site-with-baseUrl-i18n loads site -  locale fr + custom
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -1060,6 +1065,7 @@ exports[`loadSite simple-site-with-baseUrl-i18n loads site - custom outDir 1`] =
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -1293,6 +1299,7 @@ exports[`loadSite simple-site-with-baseUrl-i18n loads site - locale de 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -1526,6 +1533,7 @@ exports[`loadSite simple-site-with-baseUrl-i18n loads site - locale en 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -1759,6 +1767,7 @@ exports[`loadSite simple-site-with-baseUrl-i18n loads site - locale es 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -1992,6 +2001,7 @@ exports[`loadSite simple-site-with-baseUrl-i18n loads site - locale fr 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -2225,6 +2235,7 @@ exports[`loadSite simple-site-with-baseUrl-i18n loads site - locale it 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,
@@ -2458,6 +2469,7 @@ exports[`loadSite simple-site-with-baseUrl-i18n loads site 1`] = `
       },
       "v4": {
         "fasterByDefault": false,
+        "mdx1CompatDisabledByDefault": false,
         "removeLegacyPostBuildHeadAttribute": false,
         "siteStorageNamespacing": false,
         "useCssCascadeLayers": false,

packages/docusaurus/src/server/__tests__/configValidation.test.ts

@@ -67,6 +67,7 @@ describe('normalizeConfig', () => {
           useCssCascadeLayers: true,
           siteStorageNamespacing: true,
           fasterByDefault: true,
+          mdx1CompatDisabledByDefault: true,
         },
         faster: {
           swcJsLoader: true,
@@ -513,6 +514,7 @@ describe('markdown', () => {
   ): MarkdownConfig {
     return normalizeConfig({markdown}).markdown;
   }
+
   it('accepts undefined object', () => {
     expect(normalizeMarkdown(undefined)).toEqual(DEFAULT_CONFIG.markdown);
   });
@@ -1348,6 +1350,7 @@ describe('future', () => {
         useCssCascadeLayers: true,
         siteStorageNamespacing: true,
         fasterByDefault: true,
+        mdx1CompatDisabledByDefault: true,
       },
       faster: {
         swcJsLoader: true,
@@ -2566,6 +2569,7 @@ describe('future', () => {
         useCssCascadeLayers: true,
         siteStorageNamespacing: true,
         fasterByDefault: true,
+        mdx1CompatDisabledByDefault: true,
       };
       expect(
         normalizeConfig({
@@ -2906,5 +2910,64 @@ describe('future', () => {
         `);
       });
     });
+
+    describe('mdx1CompatDisabledByDefault', () => {
+      function mdx1CompatContaining(mdx1Compat: object) {
+        return expect.objectContaining({
+          markdown: expect.objectContaining({mdx1Compat}),
+        });
+      }
+
+      const MDX1_COMPAT_ALL_TRUE = {
+        comments: true,
+        admonitions: true,
+        headingIds: true,
+      };
+
+      const MDX1_COMPAT_ALL_FALSE = {
+        comments: false,
+        admonitions: false,
+        headingIds: false,
+      };
+
+      it('defaults mdx1Compat to all true when flag is off', () => {
+        expect(normalizeConfig({})).toEqual(
+          mdx1CompatContaining(MDX1_COMPAT_ALL_TRUE),
+        );
+      });
+
+      it('defaults mdx1Compat to all false when flag is on', () => {
+        expect(
+          normalizeConfig({
+            future: {v4: {mdx1CompatDisabledByDefault: true}},
+          }),
+        ).toEqual(mdx1CompatContaining(MDX1_COMPAT_ALL_FALSE));
+      });
+
+      it('defaults mdx1Compat to all false when v4: true', () => {
+        expect(
+          normalizeConfig({
+            future: {v4: true},
+          }),
+        ).toEqual(mdx1CompatContaining(MDX1_COMPAT_ALL_FALSE));
+      });
+
+      it('keeps explicit mdx1Compat overrides when flag is on', () => {
+        expect(
+          normalizeConfig({
+            future: {v4: {mdx1CompatDisabledByDefault: true}},
+            markdown: {
+              mdx1Compat: {admonitions: true},
+            },
+          }),
+        ).toEqual(
+          mdx1CompatContaining({
+            comments: false,
+            admonitions: true,
+            headingIds: false,
+          }),
+        );
+      });
+    });
   });
 });