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

docs: update config to new Markdoc options

Browse source
This commit is contained in:
bholmesdev 2023-03-01 14:39:59 -05:00
parent a3a187b6d3
commit 1f72257abe
1 changed files with 38 additions and 25 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -84,40 +84,49 @@ const { Content } = await entry.render();
## Configuration ## Configuration
You can configure how your Markdoc content is rendered using props via the `Content` component. This component is returned by [a content collection `render()` result](https://docs.astro.build/en/guides/content-collections/#rendering-content-to-html). Once the Markdoc integration is installed, no configuration is necessary to use `.mdoc` files in your Content Collections.
### `config` prop ### Markdoc config
The `config` prop accepts all [Markdoc configuration options](https://markdoc.dev/docs/config#full-example), including tags and variables. The Markdoc integration accepts [all Markdoc configuration options](https://markdoc.dev/docs/config), including [tags](https://markdoc.dev/docs/tags) and [variables](https://markdoc.dev/docs/variables).
This example defines a `version` variable to use within a `why-markdoc.mdoc` entry: You can pass these options from the `markdoc()` integration in your `astro.config`. This example declares a `version` variable and an `aside` tag for use across all Markdoc Content Collection entries:
```astro ```ts
--- // astro.config.mjs
import { getEntryBySlug } from 'astro:content'; import { defineConfig } from 'astro/config';
import markdoc from '@astrojs/markdoc';
const entry = await getEntryBySlug('docs', 'why-markdoc'); // https://astro.build/config
const { Content } = await entry.render(); export default defineConfig({
--- integrations: [
markdoc({
<Content variables: {
config={{ version: '0.0.1',
variables: { }
version: '0.0.1', tags: {
} aside: {
}} render: 'aside',
/> attributes: {
type: { type: String },
title: { type: String },
},
},
},
}),
],
});
``` ```
### `components` prop
The `components` prop defines mappings from an HTML element name to an Astro or UI framework component (React, Vue, Svelte, etc).
:::note :::note
`components` 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. These options will be applied during [the Markdoc "transform" phase](https://markdoc.dev/docs/render#transform). This is run **at build time** (rather than server request time) both for static and SSR Astro projects.
::: ::
This example renders all `h1` headings using a `Title` component: ### Content `components` prop
The `Content` component accepts a `components` prop, which defines mappings from an HTML element name to an Astro or UI framework component (React, Vue, Svelte, etc).
This example renders all `h1` headings using a `Title` component when rendering `src/docs/why-markdoc.mdoc`:
```astro ```astro
--- ---
@ -135,6 +144,10 @@ const { Content } = await entry.render();
/> />
``` ```
:::tip
`components` 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.
:::
## Examples ## Examples
* The [Astro Markdoc starter template](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use Markdoc files in your Astro project. * The [Astro Markdoc starter template](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use Markdoc files in your Astro project.