Skip to content

Commit 0c3c216

Browse files
delucismatthewp
delucis
authored and
matthewp
committed
Revert MDX README changes (#6062)
1 parent 680e235 commit 0c3c216

File tree

2 files changed

+32
-260
lines changed

2 files changed

+32
-260
lines changed

‎.changeset/cuddly-donkeys-warn.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@astrojs/mdx': patch
3+
---
4+
5+
Update MDX README

‎packages/integrations/mdx/README.md

Lines changed: 27 additions & 260 deletions
Original file line numberDiff line numberDiff line change
@@ -103,47 +103,19 @@ import rehypeMinifyHtml from 'rehype-minify-html';
103103
export default defineConfig({
104104
integrations: [
105105
mdx({
106-
remarkPlugins: [exampleRemarkPlugin],
107-
}),
108-
],
109-
});
110-
```
111-
112-
…every MDX file will have `customProperty` in its frontmatter! See [our Markdown documentation](https://docs.astro.build/en/guides/markdown-content/#example-injecting-frontmatter) for more usage instructions and a [reading time plugin example](https://docs.astro.build/en/guides/markdown-content/#example-calculate-reading-time).
113-
114-
### Layouts
115-
Layouts can be applied [in the same way as standard Astro Markdown](https://docs.astro.build/en/guides/markdown-content/#frontmatter-layout). You can add a `layout` to [your frontmatter](#frontmatter) like so:
116-
117-
```yaml
118-
---
119-
layout: '../layouts/BaseLayout.astro'
120-
title: 'My Blog Post'
121-
---
122-
```
123-
124-
Then, you can retrieve all other frontmatter properties from your layout via the `frontmatter` property, and render your MDX using the default [`<slot />`](https://docs.astro.build/en/core-concepts/astro-components/#slots). See [layout props](#layout-props) for a complete list of props available.
125-
126-
```astro title="src/layouts/BaseLayout.astro"
127-
---
128-
const { frontmatter, url } = Astro.props;
129-
---
130-
<html>
131-
<head>
132-
<meta rel="canonical" href={new URL(url, Astro.site).pathname}>
133-
<title>{frontmatter.title}</title>
134-
</head>
135-
<body>
136-
<h1>{frontmatter.title}</h1>
137-
<!-- Rendered MDX will be passed into the default slot. -->
138-
<slot />
139-
</body>
140-
</html>
106+
syntaxHighlight: 'shiki',
107+
shikiConfig: { theme: 'dracula' },
108+
remarkPlugins: [remarkToc],
109+
rehypePlugins: [rehypeMinifyHtml],
110+
remarkRehype: { footnoteLabel: 'Footnotes' },
111+
gfm: false,
112+
})
113+
]
114+
})
141115
```
142116

143-
You can set a layout’s [`Props` type](/en/guides/typescript/#component-props) with the `MDXLayoutProps` helper.
144-
145-
:::note
146-
`MDXLayoutProps` is the same as the `MarkdownLayoutProps` utility type with `rawContent()` and `compiledContent()` removed (since these are not available for `.mdx` files). Feel free to **use `MarkdownLayoutProps` instead** when sharing a layout across `.md` and `.mdx` files.
117+
:::caution
118+
MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead.
147119
:::
148120

149121
📚 See the [Markdown Options reference](https://docs.astro.build/en/reference/configuration-reference/#markdown-options) for a complete list of options.
@@ -157,77 +129,6 @@ MDX will extend [your project's existing Markdown configuration](https://docs.as
157129

158130
For example, say you need to disable GitHub-Flavored Markdown and apply a different set of remark plugins for MDX files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:
159131

160-
```html
161-
<blockquote>
162-
<p>A blockquote with <em>some</em> emphasis.</p>
163-
</blockquote>
164-
```
165-
166-
But what if you want to specify your own markup for these blockquotes? In the above example, you could create a custom `<Blockquote />` component (in any language) that either has a `<slot />` component or accepts a `children` prop.
167-
168-
```astro title="src/components/Blockquote.astro"
169-
---
170-
const props = Astro.props;
171-
---
172-
173-
<blockquote {...props} class="bg-blue-50 p-4">
174-
<span class="text-4xl text-blue-600 mb-2">“</span>
175-
<slot />
176-
</blockquote>
177-
```
178-
179-
Then in the MDX file you import the component and export it to the `components` export.
180-
181-
```mdx title="src/pages/posts/post-1.mdx" {2}
182-
import Blockquote from '../components/Blockquote.astro';
183-
export const components = { blockquote: Blockquote };
184-
```
185-
186-
Now, writing the standard Markdown blockquote syntax (`>`) will use your custom `<Blockquote />` component instead. No need to use a component in Markdown, or write a remark/rehype plugin! Visit the [MDX website](https://mdxjs.com/table-of-components/) for a full list of HTML elements that can be overwritten as custom components.
187-
188-
#### Custom components with imported `mdx`
189-
190-
When rendering imported MDX content, custom components can be passed via the `components` prop.
191-
192-
Note: An MDX file's exported components will _not_ be used unless you manually import and pass them via the `components` property. See the example below:
193-
194-
```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}"
195-
---
196-
import { Content, components } from '../content.mdx';
197-
import Heading from '../Heading.astro';
198-
---
199-
200-
<Content components={{...components, h1: Heading }} />
201-
```
202-
203-
### Syntax highlighting
204-
205-
The MDX integration respects [your project's `markdown.syntaxHighlight` configuration](https://docs.astro.build/en/guides/markdown-content/#syntax-highlighting).
206-
207-
We will highlight your code blocks with [Shiki](https://github.com/shikijs/shiki) by default. You can customize this highlighter using the `markdown.shikiConfig` option in your `astro.config`. For example, you can apply a different built-in theme like so:
208-
209-
__`astro.config.mjs`__
210-
211-
```js
212-
import { defineConfig } from 'astro/config';
213-
import mdx from '@astrojs/mdx';
214-
215-
export default defineConfig({
216-
markdown: {
217-
shikiConfig: {
218-
theme: 'dracula',
219-
},
220-
},
221-
integrations: [mdx()],
222-
});
223-
```
224-
225-
Visit [our Shiki configuration docs](https://docs.astro.build/en/guides/markdown-content/#shiki-configuration) for more on using Shiki with Astro.
226-
227-
#### Switch to Prism
228-
229-
You can also use the [Prism](https://prismjs.com/) syntax highlighter by setting `markdown.syntaxHighlight` to `'prism'` in your `astro.config` like so:
230-
231132
__`astro.config.mjs`__
232133

233134
```js
@@ -240,149 +141,39 @@ export default defineConfig({
240141
remarkPlugins: [remarkPlugin1],
241142
gfm: true,
242143
},
243-
integrations: [mdx()],
244-
});
245-
```
246-
247-
This applies a minimal Prism renderer with added support for `astro` code blocks. Visit [our "Prism configuration" docs](https://docs.astro.build/en/guides/markdown-content/#prism-configuration) for more on using Prism with Astro.
248-
249-
#### Switch to a custom syntax highlighter
250-
251-
You may want to apply your own syntax highlighter too. If your highlighter offers a remark or rehype plugin, you can flip off our syntax highlighting by setting `markdown.syntaxHighlight: false` and wiring up your plugin. For example, say you want to apply [Shiki Twoslash's remark plugin](https://www.npmjs.com/package/remark-shiki-twoslash):
252-
253-
__`astro.config.mjs`__
254-
255-
```js
256-
import { defineConfig } from 'astro/config';
257-
import mdx from '@astrojs/mdx';
258-
import shikiTwoslash from 'remark-shiki-twoslash';
259-
260-
export default defineConfig({
261-
markdown: {
262-
syntaxHighlight: false,
263-
},
264144
integrations: [
265145
mdx({
266-
remarkPlugins: [shikiTwoslash, { /* Shiki Twoslash config */ }],
267-
})
268-
],
269-
});
270-
```
271-
272-
## Configuration
273-
274-
### remarkPlugins
275-
276-
[Remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) allow you to extend your Markdown with new capabilities. This includes [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and more. We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) for a full curated list!
277-
278-
This example applies the [`remark-toc`](https://github.com/remarkjs/remark-toc) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendplugins).
279-
280-
__`astro.config.mjs`__
146+
// `syntaxHighlight` inherited from Markdown
281147

282-
```js
283-
import { defineConfig } from 'astro/config';
284-
import mdx from '@astrojs/mdx';
285-
import remarkToc from 'remark-toc';
286-
287-
export default defineConfig({
288-
integrations: [mdx({
289-
remarkPlugins: [remarkToc],
290-
})],
291-
});
292-
```
293-
294-
### rehypePlugins
295-
296-
[Rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md) allow you to transform the HTML that your Markdown generates. We encourage you to browse [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for a full curated list of plugins!
297-
298-
We apply our own (non-removable) [`collect-headings`](https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/rehype-collect-headings.ts) plugin. This applies IDs to all headings (i.e. `h1 -> h6`) in your MDX files to [link to headings via anchor tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page).
299-
300-
This example applies the [`rehype-minify`](https://github.com/rehypejs/rehype-minify) plugin to `.mdx` files. To customize plugin inheritance from your Markdown config or Astro's defaults, [see the `extendPlugins` option](#extendplugins).
301-
302-
__`astro.config.mjs`__
303-
304-
```js
305-
import { defineConfig } from 'astro/config';
306-
import mdx from '@astrojs/mdx';
307-
import rehypeMinifyHtml from 'rehype-minify';
308-
309-
export default defineConfig({
310-
integrations: [mdx({
311-
rehypePlugins: [rehypeMinifyHtml],
312-
})],
313-
});
314-
```
315-
316-
### extendPlugins
317-
318-
**Type:** `'markdown' | 'astroDefaults' | false`
319-
320-
**Default:** `'markdown'`
321-
322-
#### `markdown` (default)
323-
324-
By default, Astro inherits all [remark](#remarkplugins) and [rehype](#rehypeplugins) plugins from [the `markdown` option in your Astro config](https://docs.astro.build/en/guides/markdown-content/#markdown-plugins). This also respects the [`markdown.extendDefaultPlugins`](https://docs.astro.build/en/reference/configuration-reference/#markdownextenddefaultplugins) option to extend Astro's defaults. Any additional plugins you apply in your MDX config will be applied _after_ your configured Markdown plugins.
325-
326-
This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) to Markdown _and_ MDX, and [`rehype-minify`](https://github.com/rehypejs/rehype-minify) to MDX alone:
327-
328-
__`astro.config.mjs`__
329-
330-
```js
331-
import { defineConfig } from 'astro/config';
332-
import mdx from '@astrojs/mdx';
333-
import remarkToc from 'remark-toc';
334-
import rehypeMinify from 'rehype-minify';
335-
336-
export default defineConfig({
337-
markdown: {
338-
// Applied to .md and .mdx files
339-
remarkPlugins: [remarkToc],
340-
},
341-
integrations: [mdx({
342-
// Applied to .mdx files only
343-
rehypePlugins: [rehypeMinify],
344-
})],
148+
// Markdown `remarkPlugins` ignored,
149+
// only `remarkPlugin2` applied.
150+
remarkPlugins: [remarkPlugin2],
151+
// `gfm` overridden to `false`
152+
gfm: false,
153+
})
154+
]
345155
});
346156
```
347157

348158
You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`:
349159

350160
__`astro.config.mjs`__
351161

352-
```js "extendPlugins: 'astroDefaults'"
162+
```js
353163
import { defineConfig } from 'astro/config';
354164
import mdx from '@astrojs/mdx';
355-
import remarkToc from 'remark-toc';
356165

357166
export default defineConfig({
358167
markdown: {
359168
remarkPlugins: [remarkPlugin1],
360169
},
361-
integrations: [mdx({
362-
remarkPlugins: [remarkToc],
363-
// Astro defaults applied
364-
extendPlugins: 'astroDefaults',
365-
})],
366-
});
367-
```
368-
369-
#### `false`
370-
371-
If you don't want to extend any plugins, set `extendPlugins` to `false`:
372-
373-
__`astro.config.mjs`__
374-
375-
```js "extendPlugins: false"
376-
import { defineConfig } from 'astro/config';
377-
import mdx from '@astrojs/mdx';
378-
import remarkToc from 'remark-toc';
379-
380-
export default defineConfig({
381-
integrations: [mdx({
382-
remarkPlugins: [remarkToc],
383-
// Astro defaults not applied
384-
extendPlugins: false,
385-
})],
170+
integrations: [
171+
mdx({
172+
// Markdown config now ignored
173+
extendMarkdownConfig: false,
174+
// No `remarkPlugins` applied
175+
})
176+
]
386177
});
387178
```
388179

@@ -392,30 +183,6 @@ These are plugins that modify the output [estree](https://github.com/estree/estr
392183

393184
We suggest [using AST Explorer](https://astexplorer.net/) to play with estree outputs, and trying [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) for searching across JavaScript nodes.
394185

395-
### remarkRehype
396-
397-
Markdown content is transformed into HTML through remark-rehype which has [a number of options](https://github.com/remarkjs/remark-rehype#options).
398-
399-
You can use remark-rehype options in your MDX integration config file like so:
400-
401-
__`astro.config.mjs`__
402-
403-
```js
404-
import { defineConfig } from 'astro/config';
405-
import mdx from '@astrojs/mdx';
406-
407-
export default defineConfig({
408-
integrations: [mdx({
409-
remarkRehype: {
410-
footnoteLabel: 'Catatan kaki',
411-
footnoteBackLabel: 'Kembali ke konten',
412-
},
413-
})],
414-
});
415-
```
416-
417-
This inherits the configuration of `markdown.remarkRehype`. This behavior can be changed by configuring `extendPlugins`.
418-
419186
## Examples
420187

421188
* The [Astro MDX starter template](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use MDX files in your Astro project.

0 commit comments

Comments
 (0)