From 7f813777c5e44c633ff981683e2dc80443c09da6 Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Mon, 29 Aug 2022 11:09:00 -0400 Subject: [PATCH 01/17] Add Astro to site generator docs --- docs/docs/getting-started.server.mdx | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index ce3484cb6..e9aaa0116 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -636,6 +636,33 @@ well. See [Using MDX with Next.js][next-mdx] for more details. +#### Astro + +[Astro](https://astro.build/) is built on [islands architecture](https://docs.astro.build/concepts/islands/), +allowing you to use React, Vue, Svelte, and more within your MDX files. + +After [creating your first Astro project](https://astro.new/), you can [add the MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/): + +```shell +astro add mdx +# Or use "npx" on Windows +npx astro add mdx +``` + +And (optionally) add your favorite component framework(s). +You can import Markdown, Astro, and other MDX files as components +out-of-the-box. + +```shell +astro add preact +# Or use "npx" on Windows +npx astro add preact +``` + +[See our documention](https://docs.astro.build/guides/integrations-guide/mdx/) +for configuring layouts, +built-in syntax highlighting with Shiki, adding YAML frontmatter, and more. + #### Parcel [Parcel 2](https://v2.parceljs.org) has their own plugin to support MDX. From 212564d4f25647d8a33bc82cf5b1ed4a0564e364 Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Mon, 29 Aug 2022 11:28:40 -0400 Subject: [PATCH 02/17] fix: our -> "the Astro" --- docs/docs/getting-started.server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index e9aaa0116..f34b57e26 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -659,7 +659,7 @@ astro add preact npx astro add preact ``` -[See our documention](https://docs.astro.build/guides/integrations-guide/mdx/) +[See the Astro documention](https://docs.astro.build/guides/integrations-guide/mdx/) for configuring layouts, built-in syntax highlighting with Shiki, adding YAML frontmatter, and more. From 7d077fd3d0a8ad592fd836208bf1db13e852f3fd Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Wed, 31 Aug 2022 09:56:20 -0400 Subject: [PATCH 03/17] nit: shell -> sh Co-authored-by: Titus --- docs/docs/getting-started.server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index f34b57e26..5f42fbb89 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -643,7 +643,7 @@ allowing you to use React, Vue, Svelte, and more within your MDX files. After [creating your first Astro project](https://astro.new/), you can [add the MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/): -```shell +```sh astro add mdx # Or use "npx" on Windows npx astro add mdx From 3ef8d15a652e983afe6cbafb9919a81c3f9ac2ec Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Wed, 31 Aug 2022 09:56:31 -0400 Subject: [PATCH 04/17] nit: "npx" -> `npx` Co-authored-by: Titus --- docs/docs/getting-started.server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 5f42fbb89..22ea0a784 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -645,7 +645,7 @@ After [creating your first Astro project](https://astro.new/), you can [add the ```sh astro add mdx -# Or use "npx" on Windows +# Or use `npx` on Windows npx astro add mdx ``` From de19f88896b8dda7b1630b959ba959f065f4dc43 Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Wed, 31 Aug 2022 09:59:43 -0400 Subject: [PATCH 05/17] nit: shell -> sh Co-authored-by: Titus --- docs/docs/getting-started.server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 22ea0a784..ea4558764 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -653,7 +653,7 @@ And (optionally) add your favorite component framework(s). You can import Markdown, Astro, and other MDX files as components out-of-the-box. -```shell +```sh astro add preact # Or use "npx" on Windows npx astro add preact From 911b6b39fc07f78e6eb5ae5ec926cedeb391a8b3 Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Wed, 31 Aug 2022 09:59:56 -0400 Subject: [PATCH 06/17] nit: "npx" -> `npx` Co-authored-by: Titus --- docs/docs/getting-started.server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index ea4558764..9210514d9 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -655,7 +655,7 @@ out-of-the-box. ```sh astro add preact -# Or use "npx" on Windows +# Or use `npx` on Windows npx astro add preact ``` From 684151051d3d113293b141a97c967454efc34e84 Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Wed, 31 Aug 2022 10:03:35 -0400 Subject: [PATCH 07/17] nit: flip Astro doc link to front Co-authored-by: Titus --- docs/docs/getting-started.server.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 9210514d9..dbb6f4091 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -659,9 +659,9 @@ astro add preact npx astro add preact ``` -[See the Astro documention](https://docs.astro.build/guides/integrations-guide/mdx/) -for configuring layouts, -built-in syntax highlighting with Shiki, adding YAML frontmatter, and more. +To learn how to configure layouts, support YAML frontmatter, and set up Astro’s +syntax highlighting, [see Astro’s guide on their MDX +integration](https://docs.astro.build/guides/integrations-guide/mdx/). #### Parcel From 7acec7a45425e4f27082001834ef847d5a6a1b7d Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Wed, 31 Aug 2022 10:21:40 -0400 Subject: [PATCH 08/17] edit: rework install and component instructions --- docs/docs/getting-started.server.mdx | 32 +++++++++++++++++----------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index dbb6f4091..a10206c27 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -638,28 +638,36 @@ See [Using MDX with Next.js][next-mdx] for more details. #### Astro -[Astro](https://astro.build/) is built on [islands architecture](https://docs.astro.build/concepts/islands/), -allowing you to use React, Vue, Svelte, and more within your MDX files. - -After [creating your first Astro project](https://astro.new/), you can [add the MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/): +[Astro](https://astro.build/) has an [official MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/). +We recommend using [the `astro add` CLI](https://docs.astro.build/en/guides/integrations-guide/#automatic-integration-setup) +to install dependencies and update your config automatically: ```sh -astro add mdx -# Or use `npx` on Windows +# Using npm npx astro add mdx +# Using yarn +yarn astro add mdx +# Using pnpm +pnpx astro add mdx ``` -And (optionally) add your favorite component framework(s). -You can import Markdown, Astro, and other MDX files as components -out-of-the-box. +This base setup allows you to import Markdown, +[Astro](https://docs.astro.build/en/core-concepts/astro-components/), +and other MDX files as components. + +**To add support for [Preact](https://docs.astro.build/en/guides/integrations-guide/preact/), [Vue](https://docs.astro.build/en/guides/integrations-guide/vue/), [Svelte](https://docs.astro.build/en/guides/integrations-guide/svelte/) and more in your MDX,** +you can install each as a separate integration: ```sh -astro add preact -# Or use `npx` on Windows +# Using npm npx astro add preact +# Using yarn +yarn astro add preact +# Using pnpm +pnpx astro add preact ``` -To learn how to configure layouts, support YAML frontmatter, and set up Astro’s +To learn how to configure layouts, YAML frontmatter, and set up Astro’s syntax highlighting, [see Astro’s guide on their MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/). From a931775d3bab71ed4afdbcbdc9eec1ebd9a4b1b0 Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Wed, 31 Aug 2022 10:24:51 -0400 Subject: [PATCH 09/17] nit: We -> Astro --- docs/docs/getting-started.server.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index a10206c27..0e94244cf 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -639,7 +639,7 @@ See [Using MDX with Next.js][next-mdx] for more details. #### Astro [Astro](https://astro.build/) has an [official MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/). -We recommend using [the `astro add` CLI](https://docs.astro.build/en/guides/integrations-guide/#automatic-integration-setup) +Astro recommends using [the `astro add` CLI](https://docs.astro.build/en/guides/integrations-guide/#automatic-integration-setup) to install dependencies and update your config automatically: ```sh @@ -652,7 +652,7 @@ pnpx astro add mdx ``` This base setup allows you to import Markdown, -[Astro](https://docs.astro.build/en/core-concepts/astro-components/), +[Astro components](https://docs.astro.build/en/core-concepts/astro-components/), and other MDX files as components. **To add support for [Preact](https://docs.astro.build/en/guides/integrations-guide/preact/), [Vue](https://docs.astro.build/en/guides/integrations-guide/vue/), [Svelte](https://docs.astro.build/en/guides/integrations-guide/svelte/) and more in your MDX,** @@ -668,8 +668,8 @@ pnpx astro add preact ``` To learn how to configure layouts, YAML frontmatter, and set up Astro’s -syntax highlighting, [see Astro’s guide on their MDX -integration](https://docs.astro.build/guides/integrations-guide/mdx/). +syntax highlighting, [see their MDX +integration docs](https://docs.astro.build/guides/integrations-guide/mdx/). #### Parcel From 29cabe3b5687a01e0f19a7e9bc50f18b7003937d Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Fri, 2 Sep 2022 12:42:17 -0400 Subject: [PATCH 10/17] nit: one big UI framework link Co-authored-by: Sarah Rainsberger --- docs/docs/getting-started.server.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 0e94244cf..9a6de8c1e 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -655,7 +655,7 @@ This base setup allows you to import Markdown, [Astro components](https://docs.astro.build/en/core-concepts/astro-components/), and other MDX files as components. -**To add support for [Preact](https://docs.astro.build/en/guides/integrations-guide/preact/), [Vue](https://docs.astro.build/en/guides/integrations-guide/vue/), [Svelte](https://docs.astro.build/en/guides/integrations-guide/svelte/) and more in your MDX,** +**To add support for [other UI framework components](https://docs.astro.build/en/core-concepts/framework-components/) (e.g. Preact, Vue, Svelte and more) in your MDX,** you can install each as a separate integration: ```sh From 95b5e8e85bf63acc93f1ef3c564ab1fae3a7c567 Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Fri, 2 Sep 2022 13:21:19 -0400 Subject: [PATCH 11/17] fix: alphabetical sorting --- docs/docs/getting-started.server.mdx | 71 ++++++++++++++-------------- 1 file changed, 36 insertions(+), 35 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 9a6de8c1e..140e7db6f 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -481,6 +481,42 @@ Which in turn lets us choose whether to use the `@mdx-js/mdx` or ### Site generators +#### Astro + +[Astro](https://astro.build/) has an [official MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/). +Astro recommends using [the `astro add` CLI](https://docs.astro.build/en/guides/integrations-guide/#automatic-integration-setup) +to install dependencies and update your config automatically: + +```sh +# Using npm +npx astro add mdx +# Using yarn +yarn astro add mdx +# Using pnpm +pnpx astro add mdx +``` + +This base setup allows you to import Markdown, +[Astro components](https://docs.astro.build/en/core-concepts/astro-components/), +and other MDX files as components. + +**To add support for [other UI framework components](https://docs.astro.build/en/core-concepts/framework-components/) +(e.g. Preact, Vue, Svelte and more) in your MDX,** +you can install each as a separate integration: + +```sh +# Using npm +npx astro add preact +# Using yarn +yarn astro add preact +# Using pnpm +pnpx astro add preact +``` + +To learn how to configure layouts, YAML frontmatter, and set up Astro’s +syntax highlighting, [see their MDX +integration docs](https://docs.astro.build/guides/integrations-guide/mdx/). + #### Create React App (CRA) @@ -636,41 +672,6 @@ well. See [Using MDX with Next.js][next-mdx] for more details. -#### Astro - -[Astro](https://astro.build/) has an [official MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/). -Astro recommends using [the `astro add` CLI](https://docs.astro.build/en/guides/integrations-guide/#automatic-integration-setup) -to install dependencies and update your config automatically: - -```sh -# Using npm -npx astro add mdx -# Using yarn -yarn astro add mdx -# Using pnpm -pnpx astro add mdx -``` - -This base setup allows you to import Markdown, -[Astro components](https://docs.astro.build/en/core-concepts/astro-components/), -and other MDX files as components. - -**To add support for [other UI framework components](https://docs.astro.build/en/core-concepts/framework-components/) (e.g. Preact, Vue, Svelte and more) in your MDX,** -you can install each as a separate integration: - -```sh -# Using npm -npx astro add preact -# Using yarn -yarn astro add preact -# Using pnpm -pnpx astro add preact -``` - -To learn how to configure layouts, YAML frontmatter, and set up Astro’s -syntax highlighting, [see their MDX -integration docs](https://docs.astro.build/guides/integrations-guide/mdx/). - #### Parcel [Parcel 2](https://v2.parceljs.org) has their own plugin to support MDX. From 03d716e051855a8d72f72266f7a8631d7788ccf2 Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Tue, 6 Sep 2022 10:09:04 -0400 Subject: [PATCH 12/17] nit: npx only Co-authored-by: Titus --- docs/docs/getting-started.server.mdx | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 140e7db6f..0ffe340fb 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -488,12 +488,7 @@ Astro recommends using [the `astro add` CLI](https://docs.astro.build/en/guides/ to install dependencies and update your config automatically: ```sh -# Using npm npx astro add mdx -# Using yarn -yarn astro add mdx -# Using pnpm -pnpx astro add mdx ``` This base setup allows you to import Markdown, From a7d814678fb1639cf080fe54c0ee16a80ab2baab Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Tue, 6 Sep 2022 10:10:11 -0400 Subject: [PATCH 13/17] edit: preact ex -> link to framework comp docs Co-authored-by: Titus --- docs/docs/getting-started.server.mdx | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 0ffe340fb..0526bcb48 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -495,18 +495,13 @@ This base setup allows you to import Markdown, [Astro components](https://docs.astro.build/en/core-concepts/astro-components/), and other MDX files as components. -**To add support for [other UI framework components](https://docs.astro.build/en/core-concepts/framework-components/) -(e.g. Preact, Vue, Svelte and more) in your MDX,** -you can install each as a separate integration: - -```sh -# Using npm -npx astro add preact -# Using yarn -yarn astro add preact -# Using pnpm -pnpx astro add preact -``` +Optionally, if you haven’t already, you can also add Astro integrations for +frameworks such as React, Preact, Vue, Svelte, and more. +Each integration lets you use components written in that framework from within +MDX files. +See Astro’s +[Framework components](https://docs.astro.build/en/core-concepts/framework-components/) +guide for more information. To learn how to configure layouts, YAML frontmatter, and set up Astro’s syntax highlighting, [see their MDX From 159b6cf2d1177851e6c65ac008f7d1686d3c2c04 Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Tue, 6 Sep 2022 10:19:32 -0400 Subject: [PATCH 14/17] nit: simplify Astro CLI instructions --- docs/docs/getting-started.server.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 0526bcb48..4e1904f9c 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -484,8 +484,7 @@ Which in turn lets us choose whether to use the `@mdx-js/mdx` or #### Astro [Astro](https://astro.build/) has an [official MDX integration](https://docs.astro.build/guides/integrations-guide/mdx/). -Astro recommends using [the `astro add` CLI](https://docs.astro.build/en/guides/integrations-guide/#automatic-integration-setup) -to install dependencies and update your config automatically: +You can add the integration with the Astro CLI (recommended): ```sh npx astro add mdx From 2a614a7b356bf7a14f475a93f6e612a76e122af2 Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Tue, 6 Sep 2022 10:19:44 -0400 Subject: [PATCH 15/17] nit: simplify Astro framework component guide --- docs/docs/getting-started.server.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 4e1904f9c..8d402818e 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -494,13 +494,9 @@ This base setup allows you to import Markdown, [Astro components](https://docs.astro.build/en/core-concepts/astro-components/), and other MDX files as components. -Optionally, if you haven’t already, you can also add Astro integrations for -frameworks such as React, Preact, Vue, Svelte, and more. -Each integration lets you use components written in that framework from within -MDX files. -See Astro’s -[Framework components](https://docs.astro.build/en/core-concepts/framework-components/) -guide for more information. +To use [other UI framework components](https://docs.astro.build/en/core-concepts/framework-components/) +in your MDX files (e.g. Preact, Vue, Svelte and more), +see Astro’s [Framework components](https://docs.astro.build/en/core-concepts/framework-components/) guide. To learn how to configure layouts, YAML frontmatter, and set up Astro’s syntax highlighting, [see their MDX From 40186311a22397032805434cc18980673fe3bc7a Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Tue, 6 Sep 2022 10:21:59 -0400 Subject: [PATCH 16/17] nit: remove dup link --- docs/docs/getting-started.server.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index 8d402818e..b4e14aa29 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -492,10 +492,9 @@ npx astro add mdx This base setup allows you to import Markdown, [Astro components](https://docs.astro.build/en/core-concepts/astro-components/), -and other MDX files as components. - -To use [other UI framework components](https://docs.astro.build/en/core-concepts/framework-components/) -in your MDX files (e.g. Preact, Vue, Svelte and more), +and other MDX files as components. To use +other UI framework components in your MDX files +(e.g. Preact, Vue, Svelte and more), see Astro’s [Framework components](https://docs.astro.build/en/core-concepts/framework-components/) guide. To learn how to configure layouts, YAML frontmatter, and set up Astro’s From 430d1c5860027e3a7b816da6b6b645d0fc9d7080 Mon Sep 17 00:00:00 2001 From: bholmesdev Date: Tue, 6 Sep 2022 10:23:57 -0400 Subject: [PATCH 17/17] nit: remove Astro comp link --- docs/docs/getting-started.server.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/docs/getting-started.server.mdx b/docs/docs/getting-started.server.mdx index b4e14aa29..08f0d9cca 100644 --- a/docs/docs/getting-started.server.mdx +++ b/docs/docs/getting-started.server.mdx @@ -490,8 +490,7 @@ You can add the integration with the Astro CLI (recommended): npx astro add mdx ``` -This base setup allows you to import Markdown, -[Astro components](https://docs.astro.build/en/core-concepts/astro-components/), +This base setup allows you to import markdown, Astro components, and other MDX files as components. To use other UI framework components in your MDX files (e.g. Preact, Vue, Svelte and more),