Markdoc: new README for Markdoc nodes (#7225)

* docs: all-new nodes documentation

* edit: `.astro` ONLY

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* edit: `.` outside links, line break

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* edit: such as, not like

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* edit: more Astro less probs

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* edit: reviewers React to

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* edit: tagz

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

* chore: add `default: 'article'` for document

* edit: reword client-side instructions

* edit: prism stylesheet got lost

* fix: heading -> blockquote

---------

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

1 files changed, 85 insertions, 46 deletions

diff --git a/packages/integrations/markdoc/README.md b/packages/integrations/markdoc/README.md
index dd2f2d4de..011f042ee 100644
--- a/packages/integrations/markdoc/README.md
+++ b/packages/integrations/markdoc/README.md
@@ -97,13 +97,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:
 
@@ -141,9 +137,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](https://docs.astro.build/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
@@ -154,55 +152,20 @@ 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](https://docs.astro.build/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.
 
-📚 [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
-
-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.
-
-This example wraps a `Aside.tsx` component with a `ClientAside.astro` wrapper:
-
-```astro
----
-// src/components/ClientAside.astro
-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:
-
-```js
-// markdoc.config.mjs
-import { defineMarkdocConfig } from '@astrojs/markdoc/config';
-import Aside from './src/components/Aside.astro';
-
-export default defineMarkdocConfig({
-  tags: {
-    aside: {
-      render: Aside,
-      attributes: {
-        type: { type: String },
-      }
-    },
-  },
-})
-```
-
 ### Syntax highlighting
 
 `@astrojs/markdoc` provides [Shiki](https://github.com/shikijs/shiki) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks.
@@ -249,7 +212,83 @@ export default defineMarkdocConfig({
 })
 ```
 
-📚 To learn about configuring Prism stylesheets, [see our syntax highlighting guide.](https://docs.astro.build/en/guides/markdown-content/#prism-configuration)
+📚 To learn about configuring Prism stylesheets, [see our syntax highlighting guide](https://docs.astro.build/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
+
+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/core-concepts/framework-components/#nesting-framework-components) with your desired `client:` directive.
+
+This example wraps a React `Aside.tsx` component with a `ClientAside.astro` component:
+
+```astro
+---
+// 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
+// markdoc.config.mjs
+import { defineMarkdocConfig } from '@astrojs/markdoc/config';
+import ClientAside from './src/components/ClientAside.astro';
+
+export default defineMarkdocConfig({
+  tags: {
+    aside: {
+      render: ClientAside,
+      attributes: {
+        type: { type: String },
+      }
+    },
+  },
+})
+```
 
 ### Access frontmatter and content collection information from your templates