Migrate docs to MDX (en-only) (withastro#2133)

Co-authored-by: bholmesdev <[email protected]>

Author: delucis

.editorconfig

@@ -11,5 +11,5 @@ indent_style = tab
 insert_final_newline = true
 trim_trailing_whitespace = false
 
-[{.*,*.md,*.json,*.toml,*.yml,}]
+[{.*,*.md,*.mdx,*.json,*.toml,*.yml,}]
 indent_style = space

.github/labeler.yml

@@ -4,4 +4,4 @@
 - .github/workflows/**
 
 i18n:
-- any: ['src/pages/**/*.md', '!src/pages/en/**/*']
+- any: ['src/pages/**/*.mdx', '!src/pages/en/**/*']

.github/workflows/ci.yml

@@ -11,6 +11,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'pull_request_target' && github.head_ref || github.ref }}
   cancel-in-progress: true
 
+env:
+  NODE_OPTIONS: "--max_old_space_size=4096"
+
 jobs:
   eslint:
     name: Check for code issues with ESLint

.github/workflows/nightly.yml

@@ -28,7 +28,7 @@ jobs:
         with:
           branch: ci/docgen-integrations
           token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }}
-          add-paths: src/pages/en/guides/integrations-guide/*.md
+          add-paths: src/pages/en/guides/integrations-guide/*.mdx
           commit-message: 'ci: update integration docs'
           title: 'ci: update integration docs'
           body: |
@@ -55,7 +55,7 @@ jobs:
         with:
           branch: ci/docgen
           token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }}
-          add-paths: src/pages/en/reference/*.md
+          add-paths: src/pages/en/reference/*.mdx
           commit-message: 'ci: update reference docs'
           title: 'ci: update reference docs'
           body: |
@@ -82,7 +82,7 @@ jobs:
         with:
           branch: ci/docgen-errors
           token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }}
-          add-paths: src/pages/en/reference/*.md
+          add-paths: src/pages/en/reference/*.mdx
           commit-message: 'ci: update error reference docs'
           title: 'ci: update error reference docs'
           body: |

.prettierignore

@@ -3,5 +3,6 @@ node_modules
 .github
 .changeset
 *.md
+*.mdx
 src/pages/lighthouse/*.astro
 pnpm-lock.yaml

.prettierrc

@@ -7,7 +7,7 @@
   "useTabs": true,
   "overrides": [
     {
-      "files": [".*", "*.json", "*.md", "*.toml", "*.yml"],
+      "files": [".*", "*.json", "*.md", "*.mdx", "*.toml", "*.yml"],
       "options": {
         "useTabs": false
       }

astro.config.ts

@@ -1,101 +1,51 @@
+import mdx from '@astrojs/mdx';
 import preact from '@astrojs/preact';
 import { defineConfig } from 'astro/config';
 
-import { toString } from 'hast-util-to-string';
-import { h } from 'hastscript';
-import { escape } from 'html-escaper';
+import AutoImport from 'astro-auto-import';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypeSlug from 'rehype-slug';
+import remarkGFM from 'remark-gfm';
+import remarkSmartypants from 'remark-smartypants';
 
-import { astroAsides } from './integrations/astro-asides';
-import { astroCodeSnippets } from './integrations/astro-code-snippets';
-import { astroSpoilers } from './integrations/astro-spoilers';
+import { asideAutoImport, astroAsides } from './integrations/astro-asides';
+import { astroCodeSnippets, codeSnippetAutoImport } from './integrations/astro-code-snippets';
+import { astroSpoilers, spoilerAutoImport } from './integrations/astro-spoilers';
 import { sitemap } from './integrations/sitemap';
+import { autolinkConfig } from './plugins/rehype-autolink-config';
 import { rehypei18nAutolinkHeadings } from './plugins/rehype-i18n-autolink-headings';
 import { rehypeTasklistEnhancer } from './plugins/rehype-tasklist-enhancer';
 import { remarkFallbackLang } from './plugins/remark-fallback-lang';
-import { backgroundPrimary, foregroundPrimary, tokens } from './syntax-highlighting-theme';
-
-import { useTranslationsForLang } from './src/i18n/util';
-
-const AnchorLinkIcon = h(
-	'svg',
-	{
-		width: 16,
-		height: 16,
-		version: 1.1,
-		viewBox: '0 0 16 16',
-		xlmns: 'http://www.w3.org/2000/svg',
-	},
-	h('path', {
-		fillRule: 'evenodd',
-		fill: 'currentcolor',
-		d: 'M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z',
-	})
-);
-
-const createSROnlyLabel = (text: string) => {
-	const t = useTranslationsForLang('en');
-	const node = h('span.sr-only', `${t('a11y.sectionLink')} ${escape(text)}`);
-	node.properties!['is:raw'] = true;
-	return node;
-};
+import { theme } from './syntax-highlighting-theme';
 
 // https://astro.build/config
 export default defineConfig({
 	site: 'https://docs.astro.build/',
-	legacy: {
-		astroFlavoredMarkdown: true,
-	},
 	integrations: [
+		AutoImport({
+			imports: [asideAutoImport, codeSnippetAutoImport, spoilerAutoImport],
+		}),
 		preact({ compat: true }),
 		sitemap(),
 		astroAsides(),
 		astroSpoilers(),
 		astroCodeSnippets(),
+		mdx(),
 	],
 	markdown: {
 		syntaxHighlight: 'shiki',
-		shikiConfig: {
-			theme: {
-				name: 'Star gazer',
-				type: 'dark',
-				settings: tokens,
-				fg: foregroundPrimary,
-				bg: backgroundPrimary,
-			},
-		},
+		shikiConfig: { theme },
 		remarkPlugins: [
 			// These are here because setting custom plugins disables the default plugins
-			'remark-gfm',
-			['remark-smartypants', { dashes: false }],
+			remarkGFM,
+			[remarkSmartypants, { dashes: false }],
 			// Add our custom plugin that marks links to fallback language pages
 			remarkFallbackLang(),
 		],
 		rehypePlugins: [
-			'rehype-slug',
+			rehypeSlug,
 			// This adds links to headings
-			[
-				'rehype-autolink-headings',
-				{
-					properties: {
-						class: 'anchor-link',
-					},
-					behavior: 'after',
-					group: ({ tagName }) =>
-						h(`div.heading-wrapper.level-${tagName}`, {
-							tabIndex: -1,
-						}),
-					content: (heading) => [
-						h(
-							`span.anchor-icon`,
-							{
-								ariaHidden: 'true',
-							},
-							AnchorLinkIcon
-						),
-						createSROnlyLabel(toString(heading)),
-					],
-				},
-			],
+			[rehypeAutolinkHeadings, autolinkConfig],
 			// Tweak GFM task list syntax
 			rehypeTasklistEnhancer(),
 			// Translates the autolink headings anchors

integrations/astro-asides.ts

@@ -1,12 +1,16 @@
 import type { AstroIntegration } from 'astro';
-import { h } from 'hastscript';
 import type * as mdast from 'mdast';
 import remarkDirective from 'remark-directive';
 import type * as unified from 'unified';
 import { remove } from 'unist-util-remove';
 import { visit } from 'unist-util-visit';
+import { isMDXFile } from './utils/isMDX';
+import { makeComponentNode } from './utils/makeComponentNode';
 
 const AsideTagname = 'AutoImportedAside';
+export const asideAutoImport: Record<string, [string, string][]> = {
+	'~/components/Aside.astro': [['default', AsideTagname]],
+};
 
 /**
  * remark plugin that converts blocks delimited with `:::` into instances of
@@ -32,8 +36,8 @@ const AsideTagname = 'AutoImportedAside';
 function remarkAsides(): unified.Plugin<[], mdast.Root> {
 	const variants = new Set(['note', 'tip', 'caution', 'danger']);
 
-	const transformer: unified.Transformer<mdast.Root> = (tree) => {
-		visit(tree, (node) => {
+	const transformer: unified.Transformer<mdast.Root> = (tree, file) => {
+		visit(tree, (node, index, parent) => {
 			if (node.type !== 'containerDirective') return;
 			const type = node.name;
 			if (!variants.has(type)) return;
@@ -52,9 +56,12 @@ function remarkAsides(): unified.Plugin<[], mdast.Root> {
 				}
 			});
 
-			const data = node.data || (node.data = {});
-			data.hName = AsideTagname;
-			data.hProperties = h(AsideTagname, { type, title }).properties;
+			// Replace this node with the aside component it represents.
+			parent.children[index] = makeComponentNode(
+				AsideTagname,
+				{ mdx: isMDXFile(file), attributes: { type, title } },
+				...node.children
+			);
 		});
 	};
 
@@ -70,18 +77,12 @@ export function astroAsides(): AstroIntegration {
 	return {
 		name: '@astrojs/asides',
 		hooks: {
-			'astro:config:setup': ({ injectScript, updateConfig }) => {
+			'astro:config:setup': ({ updateConfig }) => {
 				updateConfig({
 					markdown: {
 						remarkPlugins: [remarkDirective, remarkAsides()],
 					},
 				});
-
-				// Auto-import the Aside component and attach it to the global scope
-				injectScript(
-					'page-ssr',
-					`import ${AsideTagname} from "~/components/Aside.astro"; global.${AsideTagname} = ${AsideTagname};`
-				);
 			},
 		},
 	};