From c7897f20a9d6e04f9cdee9a0f7e48e59adf1e59a Mon Sep 17 00:00:00 2001 From: Ben Holmes Date: Tue, 30 May 2023 14:51:38 -0400 Subject: [PATCH 1/5] Markdoc: new README for Markdoc nodes (#7225) * docs: all-new nodes documentation * edit: `.astro` ONLY Co-authored-by: Sarah Rainsberger * edit: `.` outside links, line break Co-authored-by: Sarah Rainsberger * edit: such as, not like Co-authored-by: Sarah Rainsberger * edit: more Astro less probs Co-authored-by: Sarah Rainsberger * edit: reviewers React to Co-authored-by: Sarah Rainsberger * edit: tagz Co-authored-by: Sarah Rainsberger * chore: add `default: 'article'` for document * edit: reword client-side instructions * edit: prism stylesheet got lost * fix: heading -> blockquote --------- Co-authored-by: Sarah Rainsberger --- packages/integrations/markdoc/README.md | 131 +++++++++++++++--------- 1 file 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 -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: +`@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]. + +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'; ---- - -