michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Markdoc: new README for Markdoc nodes (#7225)

Browse source 
* 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>
This commit is contained in:
Ben Holmes 2023-05-30 14:51:38 -04:00 committed by GitHub
parent 4851782197
commit c7897f20a9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 85 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

131
packages/integrations/markdoc/README.md
View file

@ -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';
---
<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