@astrojs/mdx 0.2.1 → 0.4.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
-@astrojs/mdx:build: cache hit, replaying output 2fda6b9b9d31f669
-@astrojs/mdx:build: 
-@astrojs/mdx:build: > @astrojs/mdx@0.2.1 build /home/runner/work/astro/astro/packages/integrations/mdx
-@astrojs/mdx:build: > astro-scripts build "src/**/*.ts" && tsc
-@astrojs/mdx:build: 
+@astrojs/mdx:build: cache hit, replaying output c4afb89e8a455a28
+@astrojs/mdx:build: 
+@astrojs/mdx:build: > @astrojs/mdx@0.4.0 build /home/runner/work/astro/astro/packages/integrations/mdx
+@astrojs/mdx:build: > astro-scripts build "src/**/*.ts" && tsc
+@astrojs/mdx:build: 

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @astrojs/mdx
 
+## 0.4.0
+
+### Minor Changes
+
+- [#4088](https://github.com/withastro/astro/pull/4088) [`1743fe140`](https://github.com/withastro/astro/commit/1743fe140eb58d60e26cbd11a066bb60de046e0c) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Support "layout" frontmatter property
+
+## 0.3.1
+
+### Patch Changes
+
+- [#4076](https://github.com/withastro/astro/pull/4076) [`6120a71e5`](https://github.com/withastro/astro/commit/6120a71e5425ad55a17ddac800d64a3f50273bce) Thanks [@matthewp](https://github.com/matthewp)! - Ensure file and url are always present in MDX for Astro.glob
+
+## 0.3.0
+
+### Minor Changes
+
+- [#3977](https://github.com/withastro/astro/pull/3977) [`19433eb4a`](https://github.com/withastro/astro/commit/19433eb4a4441522f68492ca914ad2ab4f061343) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Add remarkPlugins and rehypePlugins to config, with the same default plugins as our standard Markdown parser
+
+* [#4002](https://github.com/withastro/astro/pull/4002) [`3b8a74452`](https://github.com/withastro/astro/commit/3b8a7445247221100462ba035f6778b43ea180e7) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Support Prism and Shiki syntax highlighting based on project config
+
+- [#3995](https://github.com/withastro/astro/pull/3995) [`b2b367c96`](https://github.com/withastro/astro/commit/b2b367c969493aaf21c974064beb241d05228066) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Support YAML frontmatter in MDX files
+
+### Patch Changes
+
+- [#4050](https://github.com/withastro/astro/pull/4050) [`9ab66c4ba`](https://github.com/withastro/astro/commit/9ab66c4ba9bf2250990114c76b792f26d0694365) Thanks [@FredKSchott](https://github.com/FredKSchott)! - Add support for injected "page-ssr" scripts
+
+* [#3981](https://github.com/withastro/astro/pull/3981) [`61fec6304`](https://github.com/withastro/astro/commit/61fec63044e1585348e8405bee6fdf4dec635efa) Thanks [@bholmesdev](https://github.com/bholmesdev)! - Include page url in MDX glob result
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -78,9 +78,255 @@ To write your first MDX page in Astro, head to our [UI framework documentation][
 
 Also check our [Astro Integration Documentation][astro-integration] for more on integrations.
 
+### Variables
+
+MDX supports `export` statements to add variables to your templates. These variables are accessible both from the template itself _and_ as named properties when importing the template somewhere else.
+
+For instance, you can export a `title` field from an MDX page or component to use as a heading with `{JSX expressions}`:
+
+```mdx
+export const title = 'My first MDX post'
+
+# {title}
+```
+
+This `title` will be accessible from `import` and [glob](https://docs.astro.build/en/reference/api-reference/#astroglob) statements as well:
+
+```astro
+---
+// src/pages/index.astro
+const posts = await Astro.glob('./*.mdx');
+---
+
+{posts.map(post => <p>{post.title}</p>)}
+```
+
+See [the official "how MDX works" guide](https://mdxjs.com/docs/using-mdx/#how-mdx-works) for more on MDX variables.
+
+### Frontmatter
+
+Astro also supports YAML-based frontmatter out-of-the-box using the [remark-mdx-frontmatter](https://github.com/remcohaszing/remark-mdx-frontmatter) plugin. By default, all variables declared in a frontmatter fence (`---`) will be accessible via the `frontmatter` export. See the `frontmatterOptions` configuration to customize this behavior.
+
+For example, we can add a `title` and `publishDate` to an MDX page or component like so:
+
+```mdx
+---
+title: 'My first MDX post'
+publishDate: '21 September 2022'
+---
+
+# {frontmatter.title}
+```
+
+Now, this `title` and `publishDate` will be accessible from `import` and [glob](https://docs.astro.build/en/reference/api-reference/#astroglob) statements via the `frontmatter` property. This matches the behavior of [plain markdown in Astro](https://docs.astro.build/en/reference/api-reference/#markdown-files) as well!
+
+```astro
+---
+// src/pages/index.astro
+const posts = await Astro.glob('./*.mdx');
+---
+
+{posts.map(post => (
+  <Fragment>
+    <h2>{post.frontmatter.title}</h2>
+    <time>{post.frontmatter.publishDate}</time>
+  </Fragment>
+))}
+```
+
+### Layouts
+
+Layouts can be applied [in the same way as standard Astro Markdown](https://docs.astro.build/en/guides/markdown-content/#markdown-layouts). 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 `content` property, and render your MDX using the default [`<slot />`](https://docs.astro.build/en/core-concepts/astro-components/#slots):
+
+```astro
+---
+// src/layouts/BaseLayout.astro
+const { content } = Astro.props;
+---
+<html>
+  <head>
+    <title>{content.title}</title>
+  </head>
+  <body>
+    <h1>{content.title}</h1>
+    <!-- Rendered MDX will be passed into the default slot. -->
+    <slot />
+  </body>
+</html>
+```
+
+#### Importing layouts manually
+
+You may need to pass information to your layouts that does not (or cannot) exist in your frontmatter. In this case, you can import and use a [`<Layout />` component](https://docs.astro.build/en/core-concepts/layouts/) like any other component:
+
+```mdx
+---
+// src/pages/posts/first-post.mdx
+
+title: 'My first MDX post'
+publishDate: '21 September 2022'
+---
+import BaseLayout from '../layouts/BaseLayout.astro';
+
+function fancyJsHelper() {
+  return "Try doing that with YAML!";
+}
+
+<BaseLayout title={frontmatter.title} fancyJsHelper={fancyJsHelper}>
+  Welcome to my new Astro blog, using MDX!
+</BaseLayout>
+```
+Then, your values are available to you through `Astro.props` in your layout, and your MDX content will be injected into the page where your `<slot />` component is written:
+
+```astro
+---
+// src/layouts/BaseLayout.astro
+const { title, fancyJsHelper } = Astro.props;
+---
+<!-- -->
+<h1>{title}</h1>
+<slot />
+<p>{fancyJsHelper()}</p>
+<!-- -->
+```
+
+### 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 [using Shiki twoslash](https://shikijs.github.io/twoslash/). You can customize [this remark plugin](https://www.npmjs.com/package/remark-shiki-twoslash) using the `markdown.shikiConfig` option in your `astro.config`. For example, you can apply a different built-in theme like so:
+
+```js
+// astro.config.mjs
+export default {
+  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:
+
+```js
+// astro.config.mjs
+export default {
+  markdown: {
+    syntaxHighlight: 'prism',
+  },
+  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.
+
 ## Configuration
 
-There are currently no configuration options for the `@astrojs/mdx` integration. Please [open an issue](https://github.com/withastro/astro/issues/new/choose) if you have a compelling use case to share.
+<details>
+  <summary><strong>remarkPlugins</strong></summary>
+
+**Default plugins:** [remark-gfm](https://github.com/remarkjs/remark-gfm), [remark-smartypants](https://github.com/silvenon/remark-smartypants)
+
+[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!
+
+We apply [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) and [Smartypants](https://github.com/silvenon/remark-smartypants) by default. This brings some niceties like auto-generating clickable links from text (ex. `https://example.com`) and formatting quotes for readability. When applying your own plugins, you can choose to preserve or remove these defaults.
+
+To apply plugins _while preserving_ Astro's default plugins, use a nested `extends` object like so:
+
+```js
+// astro.config.mjs
+import remarkToc from 'remark-toc';
+
+export default {
+  integrations: [mdx({
+    // apply remark-toc alongside GitHub-flavored markdown and Smartypants
+    remarkPlugins: { extends: [remarkToc] },
+  })],
+}
+```
+
+To apply plugins _without_ Astro's defaults, you can apply a plain array:
+
+```js
+// astro.config.mjs
+import remarkToc from 'remark-toc';
+
+export default {
+  integrations: [mdx({
+    // apply remark-toc alone, removing other defaults
+    remarkPlugins: [remarkToc],
+  })],
+}
+```
+
+</details>
+
+<details>
+  <summary><strong>rehypePlugins</strong></summary>
+
+**Default plugins:** none
+
+[Rehype plugins](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md) allow you to transform the HTML that your Markdown generates. We recommend checking the [Remark plugin](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) catalog first _before_ considering rehype plugins, since most users want to transform their Markdown syntax instead. If HTML transforms are what you need, we encourage you to browse [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for a full curated list of plugins!
+
+To apply rehype plugins, use the `rehypePlugins` configuration option like so:
+
+```js
+// astro.config.mjs
+import rehypeMinifyHtml from 'rehype-minify';
+
+export default {
+  integrations: [mdx({
+    rehypePlugins: [rehypeMinifyHtml],
+  })],
+}
+```
+</details>
+
+<details>
+  <summary><strong>frontmatterOptions</strong></summary>
+
+**Default:** `{ name: 'frontmatter' }`
+
+We use [remark-mdx-frontmatter](https://github.com/remcohaszing/remark-mdx-frontmatter) to parse YAML-based frontmatter in your MDX files. If you want to override our default configuration or extend remark-mdx-frontmatter (ex. to [apply a custom frontmatter parser](https://github.com/remcohaszing/remark-mdx-frontmatter#parsers)), you can supply a `frontmatterOptions` configuration.
+
+For example, say you want to access frontmatter as root-level variables without a nested `frontmatter` object. You can override the [`name` configuration option](https://github.com/remcohaszing/remark-mdx-frontmatter#name) like so:
+
+```js
+// astro.config.mjs
+export default {
+  integrations: [mdx({
+    frontmatterOptions: {
+      name: '',
+    }
+  })],
+}
+```
+
+```mdx
+---
+title: I'm just a variable now!
+---
+
+# {title}
+```
+
+See the [remark-mdx-frontmatter README](https://github.com/remcohaszing/remark-mdx-frontmatter#options) for a complete list of options.
+</details>
 
 ## Examples
 

package/dist/index.d.ts

@@ -1,2 +1,18 @@
+import { Options as MdxRollupPluginOptions } from '@mdx-js/rollup';
 import type { AstroIntegration } from 'astro';
-export default function mdx(): AstroIntegration;
+import type { RemarkMdxFrontmatterOptions } from 'remark-mdx-frontmatter';
+declare type WithExtends<T> = T | {
+    extends: T;
+};
+declare type MdxOptions = {
+    remarkPlugins?: WithExtends<MdxRollupPluginOptions['remarkPlugins']>;
+    rehypePlugins?: WithExtends<MdxRollupPluginOptions['rehypePlugins']>;
+    /**
+     * Configure the remark-mdx-frontmatter plugin
+     * @see https://github.com/remcohaszing/remark-mdx-frontmatter#options for a full list of options
+     * @default {{ name: 'frontmatter' }}
+     */
+    frontmatterOptions?: RemarkMdxFrontmatterOptions;
+};
+export default function mdx(mdxOptions?: MdxOptions): AstroIntegration;
+export {};

package/dist/index.js

@@ -1,31 +1,108 @@
+import { nodeTypes } from "@mdx-js/mdx";
 import mdxPlugin from "@mdx-js/rollup";
-function mdx() {
+import { parse as parseESM } from "es-module-lexer";
+import rehypeRaw from "rehype-raw";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkMdxFrontmatter from "remark-mdx-frontmatter";
+import remarkShikiTwoslash from "remark-shiki-twoslash";
+import remarkSmartypants from "remark-smartypants";
+import remarkPrism from "./remark-prism.js";
+import { getFileInfo, getFrontmatter } from "./utils.js";
+const DEFAULT_REMARK_PLUGINS = [remarkGfm, remarkSmartypants];
+function handleExtends(config, defaults = []) {
+  if (Array.isArray(config))
+    return config;
+  return [...defaults, ...(config == null ? void 0 : config.extends) ?? []];
+}
+function mdx(mdxOptions = {}) {
   return {
     name: "@astrojs/mdx",
     hooks: {
-      "astro:config:setup": ({ updateConfig, addPageExtension, command }) => {
+      "astro:config:setup": ({ updateConfig, config, addPageExtension, command }) => {
         addPageExtension(".mdx");
+        let remarkPlugins = handleExtends(mdxOptions.remarkPlugins, DEFAULT_REMARK_PLUGINS);
+        let rehypePlugins = handleExtends(mdxOptions.rehypePlugins);
+        if (config.markdown.syntaxHighlight === "shiki") {
+          remarkPlugins.push([
+            remarkShikiTwoslash.default,
+            config.markdown.shikiConfig
+          ]);
+          rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
+        }
+        if (config.markdown.syntaxHighlight === "prism") {
+          remarkPlugins.push(remarkPrism);
+          rehypePlugins.push([rehypeRaw, { passThrough: nodeTypes }]);
+        }
+        remarkPlugins.push(remarkFrontmatter);
+        remarkPlugins.push([
+          remarkMdxFrontmatter,
+          {
+            name: "frontmatter",
+            ...mdxOptions.frontmatterOptions
+          }
+        ]);
+        const configuredMdxPlugin = mdxPlugin({
+          remarkPlugins,
+          rehypePlugins,
+          jsx: true,
+          jsxImportSource: "astro",
+          format: "mdx",
+          mdExtensions: []
+        });
         updateConfig({
           vite: {
             plugins: [
               {
                 enforce: "pre",
-                ...mdxPlugin({
-                  jsx: true,
-                  jsxImportSource: "astro",
-                  format: "mdx",
-                  mdExtensions: []
-                })
+                ...configuredMdxPlugin,
+                async transform(code, id) {
+                  var _a, _b;
+                  if (!id.endsWith(".mdx"))
+                    return;
+                  const mdxPluginTransform = (_a = configuredMdxPlugin.transform) == null ? void 0 : _a.bind(this);
+                  if ((_b = mdxOptions.frontmatterOptions) == null ? void 0 : _b.parsers) {
+                    return mdxPluginTransform == null ? void 0 : mdxPluginTransform(code, id);
+                  }
+                  const frontmatter = getFrontmatter(code, id);
+                  if (frontmatter.layout) {
+                    const { layout, ...content } = frontmatter;
+                    code += `
+export default async function({ children }) {
+const Layout = (await import(${JSON.stringify(
+                      frontmatter.layout
+                    )})).default;
+return <Layout content={${JSON.stringify(
+                      content
+                    )}}>{children}</Layout> }`;
+                  }
+                  return mdxPluginTransform == null ? void 0 : mdxPluginTransform(code, id);
+                }
               },
-              command === "dev" && {
+              {
                 name: "@astrojs/mdx",
                 transform(code, id) {
                   if (!id.endsWith(".mdx"))
                     return;
-                  return `${code}
+                  const [, moduleExports] = parseESM(code);
+                  code += `
+import "${"astro:scripts/page-ssr.js"}";`;
+                  const { fileUrl, fileId } = getFileInfo(id, config);
+                  if (!moduleExports.includes("url")) {
+                    code += `
+export const url = ${JSON.stringify(fileUrl)};`;
+                  }
+                  if (!moduleExports.includes("file")) {
+                    code += `
+export const file = ${JSON.stringify(fileId)};`;
+                  }
+                  if (command === "dev") {
+                    code += `
 if (import.meta.hot) {
 											import.meta.hot.decline();
 										}`;
+                  }
+                  return code;
                 }
               }
             ]

package/dist/remark-prism.d.ts

@@ -0,0 +1,2 @@
+/**  */
+export default function remarkPrism(): (tree: any) => void;

package/dist/remark-prism.js

@@ -0,0 +1,49 @@
+import { addAstro } from "@astrojs/prism/internal";
+import Prism from "prismjs";
+import loadLanguages from "prismjs/components/index.js";
+import { visit } from "unist-util-visit";
+const languageMap = /* @__PURE__ */ new Map([["ts", "typescript"]]);
+function runHighlighter(lang, code) {
+  let classLanguage = `language-${lang}`;
+  if (lang == null) {
+    lang = "plaintext";
+  }
+  const ensureLoaded = (language) => {
+    if (language && !Prism.languages[language]) {
+      loadLanguages([language]);
+    }
+  };
+  if (languageMap.has(lang)) {
+    ensureLoaded(languageMap.get(lang));
+  } else if (lang === "astro") {
+    ensureLoaded("typescript");
+    addAstro(Prism);
+  } else {
+    ensureLoaded("markup-templating");
+    ensureLoaded(lang);
+  }
+  if (lang && !Prism.languages[lang]) {
+    console.warn(`Unable to load the language: ${lang}`);
+  }
+  const grammar = Prism.languages[lang];
+  let html = code;
+  if (grammar) {
+    html = Prism.highlight(code, grammar, lang);
+  }
+  return { classLanguage, html };
+}
+function remarkPrism() {
+  return (tree) => visit(tree, "code", (node) => {
+    let { lang, value } = node;
+    node.type = "html";
+    let { html, classLanguage } = runHighlighter(lang, value);
+    let classes = [classLanguage];
+    node.value = `<pre class="${classes.join(
+      " "
+    )}"><code class="${classLanguage}">${html}</code></pre>`;
+    return node;
+  });
+}
+export {
+  remarkPrism as default
+};

package/dist/utils.d.ts

@@ -0,0 +1,15 @@
+import type { AstroConfig } from 'astro';
+interface FileInfo {
+    fileId: string;
+    fileUrl: string;
+}
+/** @see 'vite-plugin-utils' for source */
+export declare function getFileInfo(id: string, config: AstroConfig): FileInfo;
+/**
+ * Match YAML exception handling from Astro core errors
+ * @see 'astro/src/core/errors.ts'
+ */
+export declare function getFrontmatter(code: string, id: string): {
+    [key: string]: any;
+};
+export {};

package/dist/utils.js

@@ -0,0 +1,47 @@
+import matter from "gray-matter";
+function appendForwardSlash(path) {
+  return path.endsWith("/") ? path : path + "/";
+}
+function getFileInfo(id, config) {
+  const sitePathname = appendForwardSlash(
+    config.site ? new URL(config.base, config.site).pathname : config.base
+  );
+  let url = void 0;
+  try {
+    url = new URL(`file://${id}`);
+  } catch {
+  }
+  const fileId = id.split("?")[0];
+  let fileUrl;
+  const isPage = fileId.includes("/pages/");
+  if (isPage) {
+    fileUrl = fileId.replace(/^.*?\/pages\//, sitePathname).replace(/(\/index)?\.mdx$/, "");
+  } else if (url && url.pathname.startsWith(config.root.pathname)) {
+    fileUrl = url.pathname.slice(config.root.pathname.length);
+  } else {
+    fileUrl = fileId;
+  }
+  if (fileUrl && config.trailingSlash === "always") {
+    fileUrl = appendForwardSlash(fileUrl);
+  }
+  return { fileId, fileUrl };
+}
+function getFrontmatter(code, id) {
+  try {
+    return matter(code).data;
+  } catch (e) {
+    if (e.name === "YAMLException") {
+      const err = e;
+      err.id = id;
+      err.loc = { file: e.id, line: e.mark.line + 1, column: e.mark.column };
+      err.message = e.reason;
+      throw err;
+    } else {
+      throw e;
+    }
+  }
+}
+export {
+  getFileInfo,
+  getFrontmatter
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@astrojs/mdx",
   "description": "Use MDX within Astro",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "author": "withastro",
@@ -24,17 +24,31 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@mdx-js/rollup": "^2.1.1"
+    "@astrojs/prism": "^0.6.1",
+    "@mdx-js/mdx": "^2.1.2",
+    "@mdx-js/rollup": "^2.1.1",
+    "es-module-lexer": "^0.10.5",
+    "gray-matter": "^4.0.3",
+    "prismjs": "^1.28.0",
+    "rehype-raw": "^6.1.1",
+    "remark-frontmatter": "^4.0.1",
+    "remark-gfm": "^3.0.1",
+    "remark-mdx-frontmatter": "^2.0.2",
+    "remark-shiki-twoslash": "^3.1.0",
+    "remark-smartypants": "^2.0.0",
+    "shiki": "^0.10.1",
+    "unist-util-visit": "^4.1.0"
   },
   "devDependencies": {
     "@types/chai": "^4.3.1",
     "@types/mocha": "^9.1.1",
     "@types/yargs-parser": "^21.0.0",
-    "astro": "1.0.0-beta.73",
+    "astro": "1.0.0-rc.3",
     "astro-scripts": "0.0.6",
     "chai": "^4.3.6",
+    "linkedom": "^0.14.12",
     "mocha": "^9.2.2",
-    "linkedom": "^0.14.12"
+    "remark-toc": "^8.0.1"
   },
   "engines": {
     "node": "^14.18.0 || >=16.12.0"