tutorial use .mdx

packages/create-docusaurus/templates/README.md

@@ -4,5 +4,4 @@ Official templates provided by Docusaurus. They are designed to be selected when
 
 ## Guide to Test Templates for Developer
 
-1. `yarn install` in the root of the repo (one level above this directory).
-1. Go to any template's directory, example: `cd classic && yarn start`.
+See [parent README.md](../README.md)

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

@@ -13,8 +13,8 @@ Regular blog authors can be added to `authors.yml`.
 
 The blog post date can be extracted from filenames, such as:
 
-- `2019-05-30-welcome.md`
-- `2019-05-30-welcome/index.md`
+- `2019-05-30-welcome.mdx`
+- `2019-05-30-welcome/index.mdx`
 
 A blog post folder can be convenient to co-locate blog post images:
 

packages/create-docusaurus/templates/shared/docs/intro.mdx

@@ -44,4 +44,4 @@ The `cd` command changes the directory you're working with. In order to work wit
 
 The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
 
-Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
+Open `docs/intro.mdx` (this page) in a text editor and edit some lines: the site **reloads automatically** and displays your changes.

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/create-a-blog-post.mdx

@@ -8,7 +8,7 @@ Docusaurus creates a **page for each blog post**, but also a **blog index page**
 
 ## Create your first Post
 
-Create a file at `blog/2021-02-28-greetings.md`:
+Create a file at `blog/2021-02-28-greetings.mdx`:
 
 ```md title="blog/2021-02-28-greetings.md"
 ---

packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-page.mdx

@@ -4,10 +4,10 @@ sidebar_position: 1
 
 # Create a Page
 
-Add **Markdown or React** files to `src/pages` to create a **standalone page**:
+Add **Markdown ([MDX](https://mdxjs.com/)) or React** files to `src/pages` to create a **standalone page**:
 
 - `src/pages/index.js` → `localhost:3000/`
-- `src/pages/foo.md` → `localhost:3000/foo`
+- `src/pages/foo.mdx` → `localhost:3000/foo`
 - `src/pages/foo/bar.js` → `localhost:3000/foo/bar`
 
 ## Create your first React Page
@@ -32,9 +32,9 @@ A new page is now available at [http://localhost:3000/my-react-page](http://loca
 
 ## Create your first Markdown Page
 
-Create a file at `src/pages/my-markdown-page.md`:
+Create a file at `src/pages/my-markdown-page.mdx`:
 
-```mdx title="src/pages/my-markdown-page.md"
+```mdx title="src/pages/my-markdown-page.mdx"
 # My Markdown page
 
 This is a Markdown page

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

@@ -6,11 +6,19 @@ sidebar_position: 4
 
 Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.
 
+:::info
+
+Docusaurus is based on **[MDX](https://mdxjs.com/)**. It allows you to use **[React and JSX](https://reactjs.org/docs/introducing-jsx.html)** in Markdown documents.
+
+You can use both `.md` and `.mdx` file extensions, but **the `.mdx` extension** is recommended when using advanced features relying on React.
+
+:::
+
 ## Front Matter
 
 Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
 
-```text title="my-doc.md"
+```text title="my-doc.mdx"
 // highlight-start
 ---
 id: my-doc-id
@@ -22,7 +30,7 @@ slug: /my-custom-url
 
 ## Markdown heading
 
-Markdown text with [links](./hello.md)
+Markdown text with [links](./hello.mdx)
 ```
 
 ## Links
@@ -34,10 +42,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
 

packages/create-docusaurus/templates/shared/docs/tutorial-extras/manage-docs-versions.mdx

@@ -51,5 +51,5 @@ The docs version dropdown appears in your navbar:
 
 It is possible to edit versioned docs in their respective folder:
 
-- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`
-- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`
+- `versioned_docs/version-1.0/hello.mdx` updates `http://localhost:3000/docs/hello`
+- `docs/hello.mdx` updates `http://localhost:3000/docs/next/hello`

packages/create-docusaurus/templates/shared/docs/tutorial-extras/translate-your-site.mdx

@@ -4,7 +4,7 @@ sidebar_position: 2
 
 # Translate your site
 
-Let's translate `docs/intro.md` to French.
+Let's translate `docs/intro.mdx` to French.
 
 ## Configure i18n
 
@@ -21,15 +21,15 @@ module.exports = {
 
 ## Translate a doc
 
-Copy the `docs/intro.md` file to the `i18n/fr` folder:
+Copy the `docs/intro.mdx` file to the `i18n/fr` folder:
 
 ```bash
 mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
 
-cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
+cp docs/intro.mdx i18n/fr/docusaurus-plugin-content-docs/current/intro.mdx
 ```
 
-Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French.
+Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.mdx` in French.
 
 ## Start your localized site
 

website/docs/installation.mdx

@@ -98,14 +98,15 @@ Assuming you chose the classic template and named your site `my-website`, you wi
 ```bash
 my-website
 ├── blog
-│   ├── 2019-05-28-hola.md
-│   ├── 2019-05-29-hello-world.md
-│   └── 2020-05-30-welcome.md
+│   ├── 2019-05-28-hola.mdx
+│   ├── 2019-05-29-hello-world.mdx
+│   └── 2020-05-30-welcome.mdx
 ├── docs
-│   ├── doc1.md
-│   ├── doc2.md
-│   ├── doc3.md
-│   └── mdx.md
+│   ├── intro.mdx
+│   ├── pages.mdx
+│   ├── blog.mdx
+│   ├── docs.mdx
+│   └── markdown-features.mdx
 ├── src
 │   ├── css
 │   │   └── custom.css
@@ -121,6 +122,14 @@ my-website
 └── yarn.lock
 ```
 
+:::info
+
+Docusaurus is based on **[MDX](https://mdxjs.com/)**. It allows you to use **[React and JSX](https://reactjs.org/docs/introducing-jsx.html)** in Markdown documents.
+
+You can use both `.md` and `.mdx` file extensions, but **the `.mdx` extension** is recommended when using advanced features relying on React.
+
+:::
+
 ### Project structure rundown {#project-structure-rundown}
 
 - `/blog/` - Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting the `path` option. More details can be found in the [blog guide](blog.mdx)