Deprecating the "Authoring markdown" section and adding config docs f…

…or the new legacy flag (#1090) * Updating docs for the new legacy markdown flag * linter fix for canonical links to MDX * Update src/pages/en/guides/markdown-content.md Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> * removing the config reference since it's auto-generated 🎉 * adding back the existing markdown.mode config reference * Adding a migration guide for the legacy flag * Update src/pages/en/migrate.md Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
withastro · Jul 25, 2022 · a5c7e1e · a5c7e1e
1 parent d54b192
commit a5c7e1e
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 1 deletion.
diff --git a/src/pages/en/guides/markdown-content.md b/src/pages/en/guides/markdown-content.md
@@ -172,6 +172,10 @@ You can also pass the `--drafts` flag when running `astro build` to build draft
 
 ## Authoring Markdown
 
+:::caution[Deprecated]
+Astro no longer supports components or JSX in Markdown pages by default and may be removed in a future release. In the meantime, Astro config supports a [legacy flag](/en/reference/configuration-reference/#legacyastroflavoredmarkdown) that will enable these features in Markdown pages until you are able to migrate to [`@astrojs/mdx`](/en/guides/integrations-guide/mdx/).
+:::
+
 In addition to supporting standard Markdown syntax, Astro also extends Markdown to make your content even more expressive. Below are some Markdown features that only exist in Astro.
 
 ### Using Variables in Markdown

diff --git a/src/pages/en/migrate.md b/src/pages/en/migrate.md
@@ -27,7 +27,7 @@ Astro v1.0 RC has upgraded from Vite 2 to [Vite 3](https://vitejs.dev/). We've h
 
 ### Deprecated: `Astro.canonicalURL`
 
-You can now use the new [`Astro.url`](/en/reference/api-reference/#astrourl) helper to construct your own canonical URL from the current page/request URL.
+You can now use the new [`Astro.url`](/en/reference/api-reference/#astrourl) helper to construct your own canonical URL from the current page/request URL. 
 
 ```js
 // Before:
@@ -36,6 +36,12 @@ const canonicalURL = Astro.canonicalURL;
 const canonicalURL = new URL(Astro.url.pathname, Astro.site);
 ```
 
+### Deprecated: Components and JSX in Markdown
+
+Astro no longer supports components or JSX expressions in Markdown pages by default. For long-term support you should migrate to the [`@astrojs/mdx`](/en/guides/integrations-guide/mdx/) integration.
+
+To make migrating easier, a new [legacy flag](/en/reference/configuration-reference/#legacyastroflavoredmarkdown) can be used to re-enable previous Markdown features.
+
 ## Migrate to v1.0.0-beta
 
 On April 4, 2022 we released the Astro 1.0 Beta! 🎉