Skip to content

Commit

Permalink
chore: content reshuffling
Browse files Browse the repository at this point in the history
  • Loading branch information
@bholmesdev
bholmesdev committed Apr 2, 2024
1 parent 3abf672 commit 3d3864d
Showing 1 changed file with 79 additions and 78 deletions.
157 changes: 79 additions & 78 deletions src/content/docs/en/guides/integrations-guide/markdoc.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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"
Expand All @@ -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:

Expand All @@ -264,7 +269,7 @@ export default defineMarkdocConfig({
});
```

#### Prism
### Prism

Apply the `prism()` extension to your Markdoc config using the `extends` property.

Expand All @@ -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.

Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down

0 comments on commit 3d3864d

Please sign in to comment.