From 37125331c9a9a96ee9f909d445d8bccf0547e667 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 3 Apr 2026 17:35:44 +0200 Subject: [PATCH 1/3] update init template to .mdx extension --- ...5-28-first-blog-post.md => 2019-05-28-first-blog-post.mdx} | 2 +- ...-05-29-long-blog-post.md => 2019-05-29-long-blog-post.mdx} | 4 ++-- .../shared/blog/2021-08-26-welcome/{index.md => index.mdx} | 2 +- .../templates/shared/docs/{intro.md => intro.mdx} | 0 .../{congratulations.md => congratulations.mdx} | 2 +- .../{create-a-blog-post.md => create-a-blog-post.mdx} | 0 .../{create-a-document.md => create-a-document.mdx} | 0 .../tutorial-basics/{create-a-page.md => create-a-page.mdx} | 0 .../{deploy-your-site.md => deploy-your-site.mdx} | 0 .../shared/docs/tutorial-basics/markdown-features.mdx | 4 ++-- .../{manage-docs-versions.md => manage-docs-versions.mdx} | 0 .../{translate-your-site.md => translate-your-site.mdx} | 0 .../shared/src/pages/{markdown-page.md => markdown-page.mdx} | 0 13 files changed, 7 insertions(+), 7 deletions(-) rename packages/create-docusaurus/templates/shared/blog/{2019-05-28-first-blog-post.md => 2019-05-28-first-blog-post.mdx} (94%) rename packages/create-docusaurus/templates/shared/blog/{2019-05-29-long-blog-post.md => 2019-05-29-long-blog-post.mdx} (96%) rename packages/create-docusaurus/templates/shared/blog/2021-08-26-welcome/{index.md => index.mdx} (97%) rename packages/create-docusaurus/templates/shared/docs/{intro.md => intro.mdx} (100%) rename packages/create-docusaurus/templates/shared/docs/tutorial-basics/{congratulations.md => congratulations.mdx} (90%) rename packages/create-docusaurus/templates/shared/docs/tutorial-basics/{create-a-blog-post.md => create-a-blog-post.mdx} (100%) rename packages/create-docusaurus/templates/shared/docs/tutorial-basics/{create-a-document.md => create-a-document.mdx} (100%) rename packages/create-docusaurus/templates/shared/docs/tutorial-basics/{create-a-page.md => create-a-page.mdx} (100%) rename packages/create-docusaurus/templates/shared/docs/tutorial-basics/{deploy-your-site.md => deploy-your-site.mdx} (100%) rename packages/create-docusaurus/templates/shared/docs/tutorial-extras/{manage-docs-versions.md => manage-docs-versions.mdx} (100%) rename packages/create-docusaurus/templates/shared/docs/tutorial-extras/{translate-your-site.md => translate-your-site.mdx} (100%) rename packages/create-docusaurus/templates/shared/src/pages/{markdown-page.md => markdown-page.mdx} (100%) diff --git a/packages/create-docusaurus/templates/shared/blog/2019-05-28-first-blog-post.md b/packages/create-docusaurus/templates/shared/blog/2019-05-28-first-blog-post.mdx similarity index 94% rename from packages/create-docusaurus/templates/shared/blog/2019-05-28-first-blog-post.md rename to packages/create-docusaurus/templates/shared/blog/2019-05-28-first-blog-post.mdx index d3032efb35cf..a62ee55e1860 100644 --- a/packages/create-docusaurus/templates/shared/blog/2019-05-28-first-blog-post.md +++ b/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 */} ...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/packages/create-docusaurus/templates/shared/blog/2019-05-29-long-blog-post.md b/packages/create-docusaurus/templates/shared/blog/2019-05-29-long-blog-post.mdx similarity index 96% rename from packages/create-docusaurus/templates/shared/blog/2019-05-29-long-blog-post.md rename to packages/create-docusaurus/templates/shared/blog/2019-05-29-long-blog-post.mdx index eb4435de591c..681cf0ec358c 100644 --- a/packages/create-docusaurus/templates/shared/blog/2019-05-29-long-blog-post.md +++ b/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 `` comment to limit blog post size in the list view. +Use a `{/*` `truncate` `*/}` comment to limit blog post size in the list view. - +{/* 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 diff --git a/packages/create-docusaurus/templates/shared/blog/2021-08-26-welcome/index.md b/packages/create-docusaurus/templates/shared/blog/2021-08-26-welcome/index.mdx similarity index 97% rename from packages/create-docusaurus/templates/shared/blog/2021-08-26-welcome/index.md rename to packages/create-docusaurus/templates/shared/blog/2021-08-26-welcome/index.mdx index 349ea075f5bb..a21bccd5f379 100644 --- a/packages/create-docusaurus/templates/shared/blog/2021-08-26-welcome/index.md +++ b/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 */} Simply add Markdown files (or folders) to the `blog` directory. diff --git a/packages/create-docusaurus/templates/shared/docs/intro.md b/packages/create-docusaurus/templates/shared/docs/intro.mdx similarity index 100% rename from packages/create-docusaurus/templates/shared/docs/intro.md rename to packages/create-docusaurus/templates/shared/docs/intro.mdx diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/congratulations.md b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/congratulations.mdx similarity index 90% rename from packages/create-docusaurus/templates/shared/docs/tutorial-basics/congratulations.md rename to packages/create-docusaurus/templates/shared/docs/tutorial-basics/congratulations.mdx index 04771a00b72f..2917c3971f75 100644 --- a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/congratulations.md +++ b/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) diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-blog-post.md b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-blog-post.mdx similarity index 100% rename from packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-blog-post.md rename to packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-blog-post.mdx diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.mdx similarity index 100% rename from packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.md rename to packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-document.mdx diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-page.md b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-page.mdx similarity index 100% rename from packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-page.md rename to packages/create-docusaurus/templates/shared/docs/tutorial-basics/create-a-page.mdx diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/deploy-your-site.md b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/deploy-your-site.mdx similarity index 100% rename from packages/create-docusaurus/templates/shared/docs/tutorial-basics/deploy-your-site.md rename to packages/create-docusaurus/templates/shared/docs/tutorial-basics/deploy-your-site.mdx diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx index 35e00825ed77..c9cf4a158cab 100644 --- a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx +++ b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx @@ -34,10 +34,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 diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-extras/manage-docs-versions.md b/packages/create-docusaurus/templates/shared/docs/tutorial-extras/manage-docs-versions.mdx similarity index 100% rename from packages/create-docusaurus/templates/shared/docs/tutorial-extras/manage-docs-versions.md rename to packages/create-docusaurus/templates/shared/docs/tutorial-extras/manage-docs-versions.mdx diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-extras/translate-your-site.md b/packages/create-docusaurus/templates/shared/docs/tutorial-extras/translate-your-site.mdx similarity index 100% rename from packages/create-docusaurus/templates/shared/docs/tutorial-extras/translate-your-site.md rename to packages/create-docusaurus/templates/shared/docs/tutorial-extras/translate-your-site.mdx diff --git a/packages/create-docusaurus/templates/shared/src/pages/markdown-page.md b/packages/create-docusaurus/templates/shared/src/pages/markdown-page.mdx similarity index 100% rename from packages/create-docusaurus/templates/shared/src/pages/markdown-page.md rename to packages/create-docusaurus/templates/shared/src/pages/markdown-page.mdx From 91373a66c5d6154c5b612d4a6d50e4b50bc8812f Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 3 Apr 2026 17:44:16 +0200 Subject: [PATCH 2/3] update admonition syntax to directives --- .../shared/docs/tutorial-basics/markdown-features.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx index c9cf4a158cab..56955f4de3d0 100644 --- a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx +++ b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx @@ -80,26 +80,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 From 090fb67b23883ffd6f634b602602f900833e3a43 Mon Sep 17 00:00:00 2001 From: sebastien Date: Fri, 3 Apr 2026 17:58:13 +0200 Subject: [PATCH 3/3] Add example of heading id syntax to init template --- .../tutorial-basics/markdown-features.mdx | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx b/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx index 56955f4de3d0..e739ec4cd13a 100644 --- a/packages/create-docusaurus/templates/shared/docs/tutorial-basics/markdown-features.mdx +++ b/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