From 3d3864da094d9576fcb6e09e3197c5a3c677bb77 Mon Sep 17 00:00:00 2001
From: bholmesdev <hey@bholmes.dev>
Date: Tue, 2 Apr 2024 14:17:11 -0400
Subject: [PATCH] chore: content reshuffling

---
 .../en/guides/integrations-guide/markdoc.mdx  | 157 +++++++++---------
 1 file changed, 79 insertions(+), 78 deletions(-)

diff --git a/src/content/docs/en/guides/integrations-guide/markdoc.mdx b/src/content/docs/en/guides/integrations-guide/markdoc.mdx
index 2dca95789c272..645d722bf82af 100644
--- a/src/content/docs/en/guides/integrations-guide/markdoc.mdx
+++ b/src/content/docs/en/guides/integrations-guide/markdoc.mdx
@@ -117,7 +117,7 @@ const { Content } = await entry.render();
 
 <ReadMore>See the [Astro Content Collection docs][astro-content-collections] for more information.</ReadMore>
 
-## Markdoc config
+## Render components
 
 `@astrojs/markdoc` offers configuration options to use all of Markdoc's features and connect UI components to your content.
 
@@ -159,64 +159,69 @@ Use tags like this fancy "aside" to add some _flair_ to your docs.
 {% /aside %}
 ```
 
-### Use Astro components from npm packages and TypeScript files
+### Use client-side UI components
 
-You may need to use Astro components exposed as named exports from TypeScript or JavaScript files. This is common when using npm packages and design systems.
+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](/en/guides/framework-components/#nesting-framework-components) with your desired `client:` directive.
 
-You can pass the import name as the second argument to the `component()` function:
+This example wraps a React `Aside.tsx` component with a `ClientAside.astro` component:
+
+```astro title="src/components/ClientAside.astro"
+---
+import Aside from './Aside';
+---
+
+<Aside {...Astro.props} client:load />
+```
+
+This Astro component can now be passed to the `render` prop for any [tag][markdoc-tags] or [node][markdoc-nodes] in your config:
 
 ```js title="markdoc.config.mjs"
 import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
 
 export default defineMarkdocConfig({
   tags: {
-    tabs: {
-      render: component('@astrojs/starlight/components', 'Tabs'),
+    aside: {
+      render: component('./src/components/ClientAside.astro'),
+      attributes: {
+        type: { type: String },
+      },
     },
   },
 });
 ```
 
-This generates the following import statement internally:
-
-```ts
-import { Tabs } from '@astrojs/starlight/components';
-```
-
-### Custom headings
+### Use Astro components from npm packages and TypeScript files
 
-`@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 need to use Astro components exposed as named exports from TypeScript or JavaScript files. This is common when using npm packages and design systems.
 
-This example renders a `Heading.astro` component using the `render` property:
+You can pass the import name as the second argument to the `component()` function:
 
 ```js title="markdoc.config.mjs"
-import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';
+import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
 
 export default defineMarkdocConfig({
-  nodes: {
-    heading: {
-      ...nodes.heading, // Preserve default anchor link generation
-      render: component('./src/components/Heading.astro'),
+  tags: {
+    tabs: {
+      render: component('@astrojs/starlight/components', 'Tabs'),
     },
   },
 });
 ```
 
-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).
+This generates the following import statement internally:
 
-For example, the heading `### Level 3 heading!` will pass `level: 3` and `id: 'level-3-heading'` as component props.
+```ts
+import { Tabs } from '@astrojs/starlight/components';
+```
 
-### Partials
+## Partials
 
 You can render other Markdoc files within your content using the `{% partial %}` tag. This is useful for reusing content across multiple documents.
 
 This example renders a `_footer.mdoc` file within the entry `src/content/blog/post.mdoc`. Use the `file` attribute to pass a relative path to the partial file:
 
 :::note
-We recommend using an underscore (_) prefix for partial files or directories. This excludes partials from content collection queries.
+We recommend using an underscore `_` prefix for partial files or directories. This excludes partials from content collection queries.
 :::
 
 ```md title="src/content/blog/post.mdoc"
@@ -233,11 +238,11 @@ Social links:
 - [GitHub](https://github.com/withastro/astro)
 ```
 
-### Syntax highlighting
+## Syntax highlighting
 
 `@astrojs/markdoc` provides [Shiki](https://shiki.style) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks.
 
-#### Shiki
+### Shiki
 
 Apply the `shiki()` extension to your Markdoc config using the `extends` property. You can optionally pass a shiki configuration object:
 
@@ -264,7 +269,7 @@ export default defineMarkdocConfig({
 });
 ```
 
-#### Prism
+### Prism
 
 Apply the `prism()` extension to your Markdoc config using the `extends` property.
 
@@ -279,45 +284,54 @@ export default defineMarkdocConfig({
 
 <ReadMore>To learn about configuring Prism stylesheets, [see our syntax highlighting guide](/en/guides/markdown-content/#prism-configuration).</ReadMore>
 
-### Set the root HTML element
+<ReadMore>See the [Markdoc nodes documentation](https://markdoc.dev/docs/nodes#built-in-nodes) to learn about all the built-in nodes and attributes.</ReadMore>
 
-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:
+## 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 title="markdoc.config.mjs"
-import { defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';
+import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';
 
 export default defineMarkdocConfig({
   nodes: {
-    document: {
-      ...nodes.document, // Apply defaults for other options
-      render: null, // default 'article'
+    blockquote: {
+      ...nodes.blockquote, // Apply Markdoc's defaults for other options
+      render: component('./src/components/Quote.astro'),
     },
   },
 });
 ```
 
-### Custom Markdoc nodes / elements
+### Custom headings
 
-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.
+`@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].
 
-This example renders blockquotes with a custom `Quote.astro` component:
+This example renders a `Heading.astro` component using the `render` property:
 
 ```js title="markdoc.config.mjs"
 import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';
 
 export default defineMarkdocConfig({
   nodes: {
-    blockquote: {
-      ...nodes.blockquote, // Apply Markdoc's defaults for other options
-      render: component('./src/components/Quote.astro'),
+    heading: {
+      ...nodes.heading, // Preserve default anchor link generation
+      render: component('./src/components/Heading.astro'),
     },
   },
 });
 ```
 
-<ReadMore>See the [Markdoc nodes documentation](https://markdoc.dev/docs/nodes#built-in-nodes) to learn about all the built-in nodes and attributes.</ReadMore>
+All Markdown headings will render the `Heading.astro` component and pass the following `attributes` as component props:
 
-### Custom image components in Markdoc
+* `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.
+
+### Custom image components
 
 Astro's `<Image />` component cannot be used directly in Markdoc. However, you can configure an Astro component to override the default image node every time the native `![]()` image syntax is used, or as a custom Markdoc tag to allow you to specify additional image attributes.
 
@@ -432,38 +446,8 @@ The following steps will create a custom Markdoc image tag to display a `<figure
     {% image src="./astro-logo.png" alt="Astro Logo" width="100" height="100" caption="a caption!" %}
     ```
 
-### Use client-side UI components
-
-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](/en/guides/framework-components/#nesting-framework-components) with your desired `client:` directive.
-
-This example wraps a React `Aside.tsx` component with a `ClientAside.astro` component:
-
-```astro title="src/components/ClientAside.astro"
----
-import Aside from './Aside';
----
-
-<Aside {...Astro.props} client:load />
-```
-
-This Astro component can now be passed to the `render` prop for any [tag][markdoc-tags] or [node][markdoc-nodes] in your config:
 
-```js title="markdoc.config.mjs"
-import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
-
-export default defineMarkdocConfig({
-  tags: {
-    aside: {
-      render: component('./src/components/ClientAside.astro'),
-      attributes: {
-        type: { type: String },
-      },
-    },
-  },
-});
-```
-
-### Markdoc config
+## Advanced Markdoc configuration
 
 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).
 
@@ -497,7 +481,24 @@ Now, you can call this function from any Markdoc content entry:
 
 <ReadMore>[See the Markdoc documentation](https://markdoc.dev/docs/functions#creating-a-custom-function) for more on using variables or functions in your content.</ReadMore>
 
-### Markdoc Language Server
+### 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 title="markdoc.config.mjs"
+import { defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';
+
+export default defineMarkdocConfig({
+  nodes: {
+    document: {
+      ...nodes.document, // Apply defaults for other options
+      render: null, // default 'article'
+    },
+  },
+});
+```
+
+## Markdoc Language Server
 
 If you are using VS Code, there is an official [Markdoc language extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support) that includes syntax highlighting and autocomplete for configured tags. [See the language server on GitHub](https://github.com/markdoc/language-server.git) for more information.
 
@@ -527,7 +528,7 @@ The `schema` property contains all information to configure the language server
 
 The top-level `path` property tells the server where content is located. Since Markdoc is specific to content collections, you can use `src/content`.
 
-### Pass Markdoc variables
+## Pass Markdoc variables
 
 You may need to pass [variables][markdoc-variables] to your content. This is useful when passing SSR parameters like A/B tests.
 
@@ -567,7 +568,7 @@ export default defineMarkdocConfig({
 });
 ```
 
-### Access frontmatter from your Markdoc content
+## 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: