diff --git a/.changeset/clever-panthers-end.md b/.changeset/clever-panthers-end.md new file mode 100644 index 0000000000000..ac52a0bfb7f00 --- /dev/null +++ b/.changeset/clever-panthers-end.md @@ -0,0 +1,5 @@ +--- +'astro': patch +--- + +Error overlay will now show the error's `cause` if available. diff --git a/.changeset/cuddly-donkeys-warn.md b/.changeset/cuddly-donkeys-warn.md new file mode 100644 index 0000000000000..b3980fb2d4782 --- /dev/null +++ b/.changeset/cuddly-donkeys-warn.md @@ -0,0 +1,5 @@ +--- +'@astrojs/mdx': patch +--- + +Update MDX README diff --git a/packages/astro/src/core/errors/dev/vite.ts b/packages/astro/src/core/errors/dev/vite.ts index 57aad4e8ae20b..3a94f9749f6f8 100644 --- a/packages/astro/src/core/errors/dev/vite.ts +++ b/packages/astro/src/core/errors/dev/vite.ts @@ -118,6 +118,7 @@ export interface AstroErrorPayload { line?: number; column?: number; }; + cause?: unknown; }; } @@ -174,6 +175,7 @@ export async function getViteErrorPayload(err: ErrorWithMetadata): Promise - * InvalidComponentArgs: Invalid arguments passed to component. + * InvalidComponentArgs: Invalid arguments passed to `` component. * @description * Astro components cannot be rendered manually via a function call, such as `Component()` or `{items.map(Component)}`. Prefer the component syntax `` or `{items.map(item => )}`. */ diff --git a/packages/astro/src/core/errors/overlay.ts b/packages/astro/src/core/errors/overlay.ts index e208017a90370..bd1b10326f935 100644 --- a/packages/astro/src/core/errors/overlay.ts +++ b/packages/astro/src/core/errors/overlay.ts @@ -321,7 +321,8 @@ const style = /* css */ ` #message-hints, #stack, -#code { +#code, +#cause { border-radius: var(--roundiness); background-color: var(--box-background); } @@ -471,7 +472,8 @@ const style = /* css */ ` color: var(--error-text); } -#stack h2 { +#stack h2, +#cause h2 { color: var(--title-text); font-family: var(--font-normal); font-size: 22px; @@ -480,7 +482,8 @@ const style = /* css */ ` border-bottom: 1px solid var(--border); } -#stack-content { +#stack-content, +#cause-content { font-size: 14px; white-space: pre; line-height: 21px; @@ -488,6 +491,10 @@ const style = /* css */ ` padding: 24px; color: var(--stack-text); } + +#cause { + display: none; +} `; const overlayTemplate = /* html */ ` @@ -552,6 +559,11 @@ ${style.trim()}

Stack Trace

+ +
+

Cause

+
+
`; @@ -593,6 +605,17 @@ class ErrorOverlay extends HTMLElement { this.text('#title', err.title); this.text('#message-content', err.message, true); + const cause = this.root.querySelector('#cause'); + if (cause && err.cause) { + if (typeof err.cause === 'string') { + this.text('#cause-content', err.cause); + cause.style.display = 'block'; + } else { + this.text('#cause-content', JSON.stringify(err.cause, null, 2)); + cause.style.display = 'block'; + } + } + const hint = this.root.querySelector('#hint'); if (hint && err.hint) { this.text('#hint-content', err.hint, true); diff --git a/packages/integrations/image/README.md b/packages/integrations/image/README.md index 213d9d3bb3bc1..e3352023964a7 100644 --- a/packages/integrations/image/README.md +++ b/packages/integrations/image/README.md @@ -422,7 +422,10 @@ This can be helpful if you need to add preload links to a page's ``. --- import { getImage } from '@astrojs/image'; -const { src } = await getImage({src: '../assets/hero.png'}); +const { src } = await getImage({ + src: import('../assets/hero.png'), + alt: "My hero image" + }); --- diff --git a/packages/integrations/mdx/README.md b/packages/integrations/mdx/README.md index 30f3e4c545d18..53c3c9be95b9f 100644 --- a/packages/integrations/mdx/README.md +++ b/packages/integrations/mdx/README.md @@ -103,47 +103,19 @@ import rehypeMinifyHtml from 'rehype-minify-html'; export default defineConfig({ integrations: [ mdx({ - remarkPlugins: [exampleRemarkPlugin], - }), - ], -}); -``` - -…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). - -### Layouts -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: - -```yaml ---- -layout: '../layouts/BaseLayout.astro' -title: 'My Blog Post' ---- -``` - -Then, you can retrieve all other frontmatter properties from your layout via the `frontmatter` property, and render your MDX using the default [``](https://docs.astro.build/en/core-concepts/astro-components/#slots). See [layout props](#layout-props) for a complete list of props available. - -```astro title="src/layouts/BaseLayout.astro" ---- -const { frontmatter, url } = Astro.props; ---- - - - - {frontmatter.title} - - -

{frontmatter.title}

- - - - + syntaxHighlight: 'shiki', + shikiConfig: { theme: 'dracula' }, + remarkPlugins: [remarkToc], + rehypePlugins: [rehypeMinifyHtml], + remarkRehype: { footnoteLabel: 'Footnotes' }, + gfm: false, + }) + ] +}) ``` -You can set a layout’s [`Props` type](/en/guides/typescript/#component-props) with the `MDXLayoutProps` helper. - -:::note -`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. +:::caution +MDX does not support passing remark and rehype plugins as a string. You should install, import, and apply the plugin function instead. ::: 📚 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 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: -```html -
-

A blockquote with some emphasis.

-
-``` - -But what if you want to specify your own markup for these blockquotes? In the above example, you could create a custom `
` component (in any language) that either has a `` component or accepts a `children` prop. - -```astro title="src/components/Blockquote.astro" ---- -const props = Astro.props; ---- - -
- “ - -
-``` - -Then in the MDX file you import the component and export it to the `components` export. - -```mdx title="src/pages/posts/post-1.mdx" {2} -import Blockquote from '../components/Blockquote.astro'; -export const components = { blockquote: Blockquote }; -``` - -Now, writing the standard Markdown blockquote syntax (`>`) will use your custom `
` 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. - -#### Custom components with imported `mdx` - -When rendering imported MDX content, custom components can be passed via the `components` prop. - -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: - -```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}" ---- -import { Content, components } from '../content.mdx'; -import Heading from '../Heading.astro'; ---- - - -``` - -### Syntax highlighting - -The MDX integration respects [your project's `markdown.syntaxHighlight` configuration](https://docs.astro.build/en/guides/markdown-content/#syntax-highlighting). - -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: - -__`astro.config.mjs`__ - -```js -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; - -export default defineConfig({ - markdown: { - shikiConfig: { - theme: 'dracula', - }, - }, - integrations: [mdx()], -}); -``` - -Visit [our Shiki configuration docs](https://docs.astro.build/en/guides/markdown-content/#shiki-configuration) for more on using Shiki with Astro. - -#### Switch to Prism - -You can also use the [Prism](https://prismjs.com/) syntax highlighter by setting `markdown.syntaxHighlight` to `'prism'` in your `astro.config` like so: - __`astro.config.mjs`__ ```js @@ -240,108 +141,17 @@ export default defineConfig({ remarkPlugins: [remarkPlugin1], gfm: true, }, - integrations: [mdx()], -}); -``` - -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. - -#### Switch to a custom syntax highlighter - -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): - -__`astro.config.mjs`__ - -```js -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; -import shikiTwoslash from 'remark-shiki-twoslash'; - -export default defineConfig({ - markdown: { - syntaxHighlight: false, - }, integrations: [ mdx({ - remarkPlugins: [shikiTwoslash, { /* Shiki Twoslash config */ }], - }) - ], -}); -``` - -## Configuration - -### remarkPlugins - -[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! - -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). - -__`astro.config.mjs`__ + // `syntaxHighlight` inherited from Markdown -```js -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; -import remarkToc from 'remark-toc'; - -export default defineConfig({ - integrations: [mdx({ - remarkPlugins: [remarkToc], - })], -}); -``` - -### rehypePlugins - -[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! - -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). - -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). - -__`astro.config.mjs`__ - -```js -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; -import rehypeMinifyHtml from 'rehype-minify'; - -export default defineConfig({ - integrations: [mdx({ - rehypePlugins: [rehypeMinifyHtml], - })], -}); -``` - -### extendPlugins - -**Type:** `'markdown' | 'astroDefaults' | false` - -**Default:** `'markdown'` - -#### `markdown` (default) - -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. - -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: - -__`astro.config.mjs`__ - -```js -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; -import remarkToc from 'remark-toc'; -import rehypeMinify from 'rehype-minify'; - -export default defineConfig({ - markdown: { - // Applied to .md and .mdx files - remarkPlugins: [remarkToc], - }, - integrations: [mdx({ - // Applied to .mdx files only - rehypePlugins: [rehypeMinify], - })], + // Markdown `remarkPlugins` ignored, + // only `remarkPlugin2` applied. + remarkPlugins: [remarkPlugin2], + // `gfm` overridden to `false` + gfm: false, + }) + ] }); ``` @@ -349,40 +159,21 @@ You may also need to disable `markdown` config extension in MDX. For this, set ` __`astro.config.mjs`__ -```js "extendPlugins: 'astroDefaults'" +```js import { defineConfig } from 'astro/config'; import mdx from '@astrojs/mdx'; -import remarkToc from 'remark-toc'; export default defineConfig({ markdown: { remarkPlugins: [remarkPlugin1], }, - integrations: [mdx({ - remarkPlugins: [remarkToc], - // Astro defaults applied - extendPlugins: 'astroDefaults', - })], -}); -``` - -#### `false` - -If you don't want to extend any plugins, set `extendPlugins` to `false`: - -__`astro.config.mjs`__ - -```js "extendPlugins: false" -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; -import remarkToc from 'remark-toc'; - -export default defineConfig({ - integrations: [mdx({ - remarkPlugins: [remarkToc], - // Astro defaults not applied - extendPlugins: false, - })], + integrations: [ + mdx({ + // Markdown config now ignored + extendMarkdownConfig: false, + // No `remarkPlugins` applied + }) + ] }); ``` @@ -392,30 +183,6 @@ These are plugins that modify the output [estree](https://github.com/estree/estr 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. -### remarkRehype - -Markdown content is transformed into HTML through remark-rehype which has [a number of options](https://github.com/remarkjs/remark-rehype#options). - -You can use remark-rehype options in your MDX integration config file like so: - -__`astro.config.mjs`__ - -```js -import { defineConfig } from 'astro/config'; -import mdx from '@astrojs/mdx'; - -export default defineConfig({ - integrations: [mdx({ - remarkRehype: { - footnoteLabel: 'Catatan kaki', - footnoteBackLabel: 'Kembali ke konten', - }, - })], -}); -``` - -This inherits the configuration of `markdown.remarkRehype`. This behavior can be changed by configuring `extendPlugins`. - ## Examples * 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.