ci: update integration docs (#3334)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
Co-authored-by: delucis <delucis@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

src/content/docs/en/guides/integrations-guide/markdoc.mdx

@@ -108,13 +108,9 @@ const { Content } = await entry.render();
 
 `@astrojs/markdoc` offers configuration options to use all of Markdoc's features and connect UI components to your content.
 
-### Using components
+### Use Astro components as Markdoc tags
 
-You can add Astro components to your Markdoc using both [Markdoc tags][markdoc-tags] and HTML element [nodes][markdoc-nodes].
-
-#### Render Markdoc tags as Astro components
-
-You may configure [Markdoc tags][markdoc-tags] that map to components. You can configure a new tag by creating a `markdoc.config.mjs|ts` file at the root of your project and configuring the `tag` attribute.
+You can configure [Markdoc tags][markdoc-tags] that map to `.astro` components. You can add a new tag by creating a `markdoc.config.mjs|ts` file at the root of your project and configuring the `tag` attribute.
 
 This example renders an `Aside` component, and allows a `type` prop to be passed as a string:
 
@@ -152,9 +148,11 @@ Use tags like this fancy "aside" to add some *flair* to your docs.
 {% /aside %}
 ```
 
-#### Render Markdoc nodes / HTML elements as Astro components
+### Custom headings
+
+`@astrojs/markdoc` automatically adds anchor links to your headings, and [generates a list of `headings` via the content collections API](/en/guides/content-collections/#rendering-content-to-html). To further customize how headings are rendered, you can apply an Astro component [as a Markdoc node][markdoc-nodes].
 
-You may also want to map standard HTML elements like headings and paragraphs to components. For this, you can configure a custom [Markdoc node][markdoc-nodes]. This example overrides Markdoc's `heading` node to render a `Heading` component, and passes through Astro's default heading properties to define attributes and generate heading ids / slugs:
+This example renders a `Heading.astro` component using the `render` property:
 
 ```js
 // markdoc.config.mjs
@@ -165,26 +163,115 @@ export default defineMarkdocConfig({
   nodes: {
     heading: {
       render: Heading,
+      // Preserve default anchor link generation
       ...nodes.heading,
     },
   },
 })
 ```
 
-All Markdown headings will render the `Heading.astro` component and pass `attributes` as component props. For headings, Astro provides the following attributes by default:
+All Markdown headings will render the `Heading.astro` component and pass the following `attributes` as component props:
 
 *   `level: number` The heading level 1 - 6
 *   `id: string` An `id` generated from the heading's text contents. This corresponds to the `slug` generated by the [content `render()` function](/en/guides/content-collections/#rendering-content-to-html).
 
 For example, the heading `### Level 3 heading!` will pass `level: 3` and `id: 'level-3-heading'` as component props.
 
+### Syntax highlighting
+
+`@astrojs/markdoc` provides [Shiki](https://github.com/shikijs/shiki) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks.
+
+#### Shiki
+
+Apply the `shiki()` extension to your Markdoc config using the `extends` property. You can optionally pass a shiki configuration object:
+
+```js
+// markdoc.config.mjs
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import shiki from '@astrojs/markdoc/shiki';
+
+export default defineMarkdocConfig({
+  extends: [
+    shiki({
+      // Choose from Shiki's built-in themes (or add your own)
+      // Default: 'github-dark'
+      // https://github.com/shikijs/shiki/blob/main/docs/themes.md
+      theme: 'dracula',
+      // Enable word wrap to prevent horizontal scrolling
+      // Default: false
+      wrap: true,
+      // Pass custom languages
+      // Note: Shiki has countless langs built-in, including `.astro`!
+      // https://github.com/shikijs/shiki/blob/main/docs/languages.md
+      langs: [],
+    })
+  ],
+})
+```
+
+#### Prism
+
+Apply the `prism()` extension to your Markdoc config using the `extends` property.
+
+```js
+// markdoc.config.mjs
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import prism from '@astrojs/markdoc/prism';
+
+export default defineMarkdocConfig({
+  extends: [prism()],
+})
+```
+
+📚 To learn about configuring Prism stylesheets, [see our syntax highlighting guide](/en/guides/markdown-content/#prism-configuration).
+
+### Set the root HTML element
+
+Markdoc wraps documents with an `<article>` tag by default. This can be changed from the `document` Markdoc node. This accepts an HTML element name or `null` if you prefer to remove the wrapper element:
+
+```js
+// markdoc.config.mjs
+import { defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';
+
+export default defineMarkdocConfig({
+  nodes: {
+    document: {
+      render: null, // default 'article'
+      ...nodes.document, // Apply defaults for other options
+    },
+  },
+})
+```
+
+### Custom Markdoc nodes / elements
+
+You may want to render standard Markdown elements, such as paragraphs and bolded text, as Astro components. For this, you can configure a [Markdoc node][markdoc-nodes]. If a given node receives attributes, they will be available as component props.
+
+This example renders blockquotes with a custom `Quote.astro` component:
+
+```js
+// markdoc.config.mjs
+import { defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';
+import Quote from './src/components/Quote.astro';
+
+export default defineMarkdocConfig({
+  nodes: {
+    blockquote: {
+      render: Quote,
+      // Apply Markdoc's defaults for other options
+      ...nodes.blockquote,
+    },
+  },
+})
+```
+
 📚 [Find all of Markdoc's built-in nodes and node attributes on their documentation.](https://markdoc.dev/docs/nodes#built-in-nodes)
 
-#### Use client-side UI components
+### Use client-side UI components
 
-Today, the `components` prop does not support the `client:` directive for hydrating components. To embed client-side components, create a wrapper `.astro` file to import your component and apply a `client:` directive manually.
+Tags and nodes are restricted to `.astro` files. To embed client-side UI components in Markdoc, [use a wrapper `.astro` component that renders a framework component](https://github.com/withastro/astro/tree/main/packages/integrations/markdoc/en/core-concepts/framework-components/#nesting-framework-components) with your desired `client:` directive.
 
-This example wraps a `Aside.tsx` component with a `ClientAside.astro` wrapper:
+This example wraps a React `Aside.tsx` component with a `ClientAside.astro` component:
 
 ```astro
 ---
@@ -195,17 +282,17 @@ import Aside from './Aside';
 <Aside {...Astro.props} client:load />
 ```
 
-This component can be passed to the `render` prop for any [tag][markdoc-tags] or [node][markdoc-nodes] in your config:
+This Astro component can now be passed to the `render` prop for any [tag][markdoc-tags] or [node][markdoc-nodes] in your config:
 
 ```js
 // markdoc.config.mjs
 import { defineMarkdocConfig } from '@astrojs/markdoc/config';
-import Aside from './src/components/Aside.astro';
+import ClientAside from './src/components/ClientAside.astro';
 
 export default defineMarkdocConfig({
   tags: {
     aside: {
-      render: Aside,
+      render: ClientAside,
       attributes: {
         type: { type: String },
       }
@@ -214,20 +301,6 @@ export default defineMarkdocConfig({
 })
 ```
 
-### Access frontmatter and content collection information from your templates
-
-You can access content collection information from your Markdoc templates using the `$entry` variable. This includes the entry `slug`, `collection` name, and frontmatter `data` parsed by your content collection schema (if any). This example renders the `title` frontmatter property as a heading:
-
-```md
----
-title: Welcome to Markdoc 👋
----
-
-# {% $entry.data.title %}
-```
-
-The `$entry` object matches [the `CollectionEntry` type](/en/reference/api-reference/#collection-entry-type), excluding the `.render()` property.
-
 ### Markdoc config
 
 The `markdoc.config.mjs|ts` file accepts [all Markdoc configuration options](https://markdoc.dev/docs/config), including [tags](https://markdoc.dev/docs/tags) and [functions](https://markdoc.dev/docs/functions).
@@ -303,6 +376,23 @@ export default defineMarkdocConfig({
 })
 ```
 
+### Access frontmatter from your Markdoc content
+
+To access frontmatter, you can pass the entry `data` property [as a variable](#pass-markdoc-variables) where you render your content:
+
+```astro
+---
+import { getEntry } from 'astro:content';
+
+const entry = await getEntry('docs', 'why-markdoc');
+const { Content } = await entry.render();
+---
+
+<Content frontmatter={entry.data} />
+```
+
+This can now be accessed as `$frontmatter` in your Markdoc.
+
 ## Examples
 
 *   The [Astro Markdoc starter template](https://github.com/withastro/astro/tree/latest/examples/with-markdoc) shows how to use Markdoc files in your Astro project.

src/content/docs/en/guides/integrations-guide/mdx.mdx

@@ -95,6 +95,7 @@ You can configure how your MDX is rendered with the following options:
 *   [Options inherited from Markdown config](#options-inherited-from-markdown-config)
 *   [`extendMarkdownConfig`](#extendmarkdownconfig)
 *   [`recmaPlugins`](#recmaplugins)
+*   [`optimize`](#optimize)
 
 ### Options inherited from Markdown config
 
@@ -195,6 +196,71 @@ These are plugins that modify the output [estree](https://github.com/estree/estr
 
 We suggest [using AST Explorer](https://astexplorer.net/) to play with estree outputs, and trying [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) for searching across JavaScript nodes.
 
+### `optimize`
+
+*   **Type:** `boolean | { customComponentNames?: string[] }`
+
+This is an optional configuration setting to optimize the MDX output for faster builds and rendering via an internal rehype plugin. This may be useful if you have many MDX files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your site's interactive parts still work correctly after enabling it.
+
+This is disabled by default. To enable MDX optimization, add the following to your MDX integration configuration:
+
+**`astro.config.mjs`**
+
+```js
+import { defineConfig } from 'astro/config';
+import mdx from '@astrojs/mdx';
+
+export default defineConfig({
+  integrations: [
+    mdx({
+      optimize: true,
+    })
+  ]
+});
+```
+
+#### `customComponentNames`
+
+*   **Type:** `string[]`
+
+An optional property of `optimize` to prevent the MDX optimizer from handling any [custom components passed to imported MDX content via the components prop](/en/guides/markdown-content/#custom-components-with-imported-mdx).
+
+You will need to exclude these components from optimization as the optimizer eagerly converts content into a static string, which will break custom components that needs to be dynamically rendered.
+
+For example, the intended MDX output of the following is `<Heading>...</Heading>` in place of every `"<h1>...</h1>"`:
+
+```astro
+---
+import { Content, components } from '../content.mdx';
+import Heading from '../Heading.astro';
+---
+
+<Content components={{...components, h1: Heading }} />
+```
+
+To configure optimization for this using the `customComponentNames` property, specify an array of HTML element names that should be treated as custom components:
+
+**`astro.config.mjs`**
+
+```js
+import { defineConfig } from 'astro/config';
+import mdx from '@astrojs/mdx';
+
+export default defineConfig({
+  integrations: [
+    mdx({
+      optimize: {
+        // Prevent the optimizer from handling `h1` elements
+        // These will be treated as custom components
+        customComponentNames: ['h1'],
+      },
+    })
+  ]
+});
+```
+
+Note that if your MDX file [configures custom components using `export const components = { ... }`](/en/guides/markdown-content/#assigning-custom-components-to-html-elements), then you do not need to manually configure this option. The optimizer will automatically detect them.
+
 ## Examples
 
 *   The [Astro MDX starter template](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use MDX files in your Astro project.

src/content/docs/en/guides/integrations-guide/partytown.mdx

@@ -144,6 +144,8 @@ export default defineConfig ({
 
 ## Troubleshooting
 
+*   If you're getting a `Failed to fetch` error, make sure you're not using any browser extensions that are blocking the script.
+
 For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!
 
 You can also check our [Astro Integration Documentation][astro-integration] for more on integrations.

src/content/docs/en/guides/integrations-guide/vercel.mdx

@@ -123,7 +123,7 @@ export default defineConfig({
 });
 ```
 
-### imageConfig
+### imagesConfig
 
 **Type:** `VercelImageConfig`<br/>
 **Available for:** Edge, Serverless, Static
@@ -139,7 +139,7 @@ import vercel from '@astrojs/vercel/static';
 export default defineConfig({
   output: 'server',
   adapter: vercel({
-    imageConfig: {
+    imagesConfig: {
       sizes: [320, 640, 1280]
     }
   })

src/content/docs/en/guides/migrate-to-astro/from-gitbook.mdx

@@ -69,7 +69,7 @@ Note that although you now have your content migrated to your Astro project, it
 
 - Astro's [Markdoc integration](/en/guides/integrations-guide/markdoc/) requires that the file extension be `.mdoc`. This is to avoid conflicts with other Markdown extensions like `.mdx` and `.md`.
 - GitBook syntax differs from Markdoc where the `/` prefix denoting a closing tag is replaced with `end` for GitBook files. You will need to update this notation throughout your files.
-- Some features of GitBook rely on custom components. These components will not exist in Astro and must be created and added to your project through [Markdoc's config `tags` attribute](/en/guides/integrations-guide/markdoc/#render-markdoc-tags-as-astro-components) or removed from your files.
+- Some features of GitBook rely on custom components. These components will not exist in Astro and must be created and added to your project through [Markdoc's config `tags` attribute](/en/guides/integrations-guide/markdoc/#use-astro-components-as-markdoc-tags) or removed from your files.
 
 ## Community Resources
 

src/content/docs/es/guides/migrate-to-astro/from-gitbook.mdx

@@ -69,7 +69,7 @@ Ten en cuenta que aunque ahora tienes tu contenido migrado a tu proyecto de Astr
 
 - La integración de [Markdoc de Astro](/es/guides/integrations-guide/markdoc/) requiere que la extensión del archivo sea `.mdoc`. Esto es para evitar conflictos con otras extensiones de Markdown como `.mdx` y `.md`.
 - La sintaxis de GitBook difiere de Markdoc donde el prefijo `/` que denota una etiqueta de cierre se reemplaza con `end` para los archivos de GitBook. Necesitarás actualizar esta notación en todos tus archivos.
-- Algunas características de GitBook dependen de componentes personalizados. Estos componentes no existirán en Astro y deben ser creados y agregados a tu proyecto a traves [del atributo `tags` de la configuración de Markdoc](/es/guides/integrations-guide/markdoc/#render-markdoc-tags-as-astro-components) o eliminados de tus archivos.
+- Algunas características de GitBook dependen de componentes personalizados. Estos componentes no existirán en Astro y deben ser creados y agregados a tu proyecto a traves [del atributo `tags` de la configuración de Markdoc](/es/guides/integrations-guide/markdoc/#use-astro-components-as-markdoc-tags) o eliminados de tus archivos.
 
 ## Recursos de la comunidad