feat: New Markdoc render API

[bholmesdev]

Changes

markdoc-config-changes.mp4

Introduce a new API (yes, another one) for adding components to your Markdoc config. Instead of importing components directly, you can use the component() utility to reference components by pathname:

import { component, defineMarkdocConfig } from '@astrojs/markdoc/config';

export default defineMarkdocConfig({
  tags: {
    aside: {
      // For local files
      render: component('./src/components/MyAside.astro'),
    },
    tabs: {
      // For npm packages with named exports
      render: component('@astrojs/starlight/components', 'Tabs'),
    }
  }
});

Why the change?

• Allows the Markdoc config to be read directly without esbuild hacks to "stub out" .astro component imports. This should unlock Markdoc's language server as well.
• Allow Astro components from npm packages and index files. We used a naive assumption before to stub .astro imports by file extension. Without this requirement, you can now use Astro components from anywhere!
• Resolves @astrojs/markdoc v0.3.1 (reprise of issue #7170): Markdoc tag rendering Astro component breaks when component uses getEntryBySlug() #7317 - component imports are now inlined on the .mdoc module itself, instead of using a propagated assets flag, which removes Markdoc-specific content collection bugs. This removes our complex resolveId() code and leans on the same propagated assets logic as Markdown and MDX.

Testing

• Update test fixtures to use new config format.

Docs

• Update Markdoc README

[changeset-bot]

🦋 Changeset detected

Latest commit: 460104a

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[bholmesdev]

!preview markdoc-component-config

[bluwy]

Setting a very high bar for PR vids here 😲

The changes looks good to me, but I'm curious if we're fine with losing autocompletion for the component imports. I'm leaning towards being fine here as it's lesser bundling and magic. Also, are we able to remove the esbuild bundling entirely now?

Side note: I noticed a pattern where external components tend to make rendering slower. MDX has a new option similar to markdoc now likely for the same reason.

[bholmesdev]

@bluwy

are we able to remove the esbuild bundling entirely now?

We still need it to process .ts configs to evaluate at build time, so not quite! We could use Vite's config loader instead of maintaining our own though 👀

I'm curious if we're fine with losing autocompletion for the component imports

I was working on a code-gen solution to glob any .astro files in src and offer autocomplete for those. This would actually be better than our existing solution, because importing .astro files in a .ts file raises lint errors when you're outside of src. I removed it as out-of-scope so I could ship something though 🙃

Side note: I noticed a pattern where external components tend to make rendering slower. MDX has a new option similar to markdoc now likely for the same reason.

This is interesting... but I'm not sure it applies to Markdoc? Markdoc doesn't "compile" components at all. We instead ship a tree of nodes to the runtime, and recurse through to find and render any components found. I'd assume this works the same regardless or where the component came from 🤷

[bluwy]

We still need it to process .ts configs to evaluate at build time, so not quite! We could use Vite's config loader instead of maintaining our own though 👀

I forgot about that! Let's keep it then to not make too many changes.

I was working on a code-gen solution to glob any .astro files in src and offer autocomplete for those.

That's also an interesting approach. Have a small concern if it would scan to many files initially since Astro components can be anywhere, but I'm good if there's plan to tackle this in the future.

This is interesting... but I'm not sure it applies to Markdoc? Markdoc doesn't "compile" components at all. We instead ship a tree of nodes to the runtime, and recurse through to find and render any components found. I'd assume this works the same regardless or where the component came from 🤷

Not familiar with the entire markdoc pipeline so I might be wrong, but I assume mixing Astro component rendering inside Markdoc rendering would slow it down, because instead of return `<p>hello world</p>` you'd have to do return `<p>hello ${render(World)}</p>` . In a way, Markdoc compiling to tree of nodes is also the same as compiled JSX 🤔

But anyways I don't want to get side-tracked with this PR 😬

[bluwy]

LGTM. Also curious to see if others have thoughts on this change

[sarah11918]

Looks great, @bholmesdev! Just a tiny nit and maybe a more explicit migration instruction to consider!

[bholmesdev]

!preview markdoc-config-changes

[github-actions]

 > [email protected] release /home/runner/work/astro/astro > pnpm run build && changeset publish "--tag" "next--markdoc-config-changes" > [email protected] build /home/runner/work/astro/astro > turbo run build --filter=astro --filter=create-astro --filter="@astrojs/*" --filter="@benchmark/*" �[2m• Packages in scope: @astrojs/alpinejs, @astrojs/cloudflare, @astrojs/deno, @astrojs/image, @astrojs/internal-helpers, @astrojs/lit, @astrojs/markdoc, @astrojs/markdown-component, @astrojs/markdown-remark, @astrojs/mdx, @astrojs/netlify, @astrojs/node, @astrojs/partytown, @astrojs/preact, @astrojs/prefetch, @astrojs/prism, @astrojs/react, @astrojs/rss, @astrojs/sitemap, @astrojs/solid-js, @astrojs/svelte, @astrojs/tailwind, @astrojs/telemetry, @astrojs/turbolinks, @astrojs/underscore-redirects, @astrojs/vercel, @astrojs/vue, @astrojs/webapi, @benchmark/timer, astro, create-astro�[0m �[2m• Running�[0m �[2m�[1mbuild�[0m�[0m �[2min 31 packages�[0m �[2m• Remote caching enabled�[0m �[35m@astrojs/webapi:build: �[0mcache hit, suppressing logs �[2m22131898d4fb04cf�[0m �[32mcreate-astro:build: �[0mcache hit, suppressing logs �[2m8923896110073887�[0m �[33m@astrojs/prism:build: �[0mcache hit, suppressing logs �[2me3cea146b484afb4�[0m �[35m@astrojs/telemetry:build: �[0mcache hit, suppressing logs �[2md5b919ea2e9792d8�[0m �[36m@astrojs/markdown-remark:build: �[0mcache hit, suppressing logs �[2m7f2fac8775910a9f�[0m �[34m@astrojs/internal-helpers:build: �[0mcache miss, executing �[2m0f7ddebbfb7c84ba�[0m �[34m@astrojs/internal-helpers:build: �[0m �[34m@astrojs/internal-helpers:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/internal-helpers �[34m@astrojs/internal-helpers:build: �[0m> astro-scripts build "src/**/*.ts" && tsc -p tsconfig.json �[34m@astrojs/internal-helpers:build: �[0m �[32mastro:build: �[0mcache miss, executing �[2m62318321cf40edc3�[0m �[32mastro:build: �[0m �[32mastro:build: �[0m> [email protected] build /home/runner/work/astro/astro/packages/astro �[32mastro:build: �[0m> pnpm run prebuild && astro-scripts build "src/**/*.{ts,js}" && tsc && pnpm run postbuild �[32mastro:build: �[0m �[32mastro:build: �[0m �[32mastro:build: �[0m> [email protected] prebuild /home/runner/work/astro/astro/packages/astro �[32mastro:build: �[0m> astro-scripts prebuild --to-string "src/runtime/server/astro-island.ts" "src/runtime/client/{idle,load,media,only,visible}.ts" �[32mastro:build: �[0m �[32mastro:build: �[0m �[32mastro:build: �[0m> [email protected] postbuild /home/runner/work/astro/astro/packages/astro �[32mastro:build: �[0m> astro-scripts copy "src/**/*.astro" && astro-scripts copy "src/**/*.wasm" �[32mastro:build: �[0m �[36m@astrojs/vue:build: �[0mcache miss, executing �[2me7cab0d86136a057�[0m �[32m@astrojs/solid-js:build: �[0mcache miss, executing �[2mb427c0d7a2f361ed�[0m �[33m@astrojs/alpinejs:build: �[0mcache miss, executing �[2m0329888151be12a6�[0m �[35m@astrojs/node:build: �[0mcache miss, executing �[2m8d0d4260ac66250a�[0m �[32m@astrojs/prefetch:build: �[0mcache miss, executing �[2m02746b52b17bbc1e�[0m �[36m@astrojs/image:build: �[0mcache miss, executing �[2m510d4eb2ae6092e5�[0m �[35m@astrojs/partytown:build: �[0mcache miss, executing �[2m994d5b71c2d5910e�[0m �[34m@astrojs/lit:build: �[0mcache miss, executing �[2mabbd816094969ef8�[0m �[34m@astrojs/tailwind:build: �[0mcache miss, executing �[2m523ce95e1f7bd0f8�[0m �[33m@astrojs/turbolinks:build: �[0mcache miss, executing �[2mfcad7afdbe7389ac�[0m �[33m@astrojs/alpinejs:build: �[0m �[33m@astrojs/alpinejs:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/alpinejs �[33m@astrojs/alpinejs:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[33m@astrojs/alpinejs:build: �[0m �[36m@astrojs/vue:build: �[0m �[36m@astrojs/vue:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/vue �[36m@astrojs/vue:build: �[0m> astro-scripts build "src/index.ts" && astro-scripts build "src/editor.cts" --force-cjs --no-clean-dist && tsc �[36m@astrojs/vue:build: �[0m �[36m@astrojs/image:build: �[0m �[36m@astrojs/image:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/image �[36m@astrojs/image:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[36m@astrojs/image:build: �[0m �[35m@astrojs/partytown:build: �[0m �[35m@astrojs/partytown:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/partytown �[35m@astrojs/partytown:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[35m@astrojs/partytown:build: �[0m �[35m@astrojs/node:build: �[0m �[35m@astrojs/node:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/node �[35m@astrojs/node:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[35m@astrojs/node:build: �[0m �[32m@astrojs/solid-js:build: �[0m �[32m@astrojs/solid-js:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/solid �[32m@astrojs/solid-js:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[32m@astrojs/solid-js:build: �[0m �[32m@astrojs/prefetch:build: �[0m �[32m@astrojs/prefetch:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/prefetch �[32m@astrojs/prefetch:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[32m@astrojs/prefetch:build: �[0m �[34m@astrojs/tailwind:build: �[0m �[34m@astrojs/tailwind:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/tailwind �[34m@astrojs/tailwind:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[34m@astrojs/tailwind:build: �[0m �[34m@astrojs/lit:build: �[0m �[34m@astrojs/lit:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/lit �[34m@astrojs/lit:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[34m@astrojs/lit:build: �[0m �[33m@astrojs/turbolinks:build: �[0m �[33m@astrojs/turbolinks:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/turbolinks �[33m@astrojs/turbolinks:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[33m@astrojs/turbolinks:build: �[0m �[33m@astrojs/react:build: �[0mcache miss, executing �[2m175bac69b20c1226�[0m �[34m@astrojs/underscore-redirects:build: �[0mcache miss, executing �[2m3f91355a33545e2f�[0m �[36m@astrojs/vercel:build: �[0mcache miss, executing �[2meff47003b12875d6�[0m �[35m@astrojs/svelte:build: �[0mcache miss, executing �[2mb57065c811e7e693�[0m �[32m@benchmark/timer:build: �[0mcache miss, executing �[2mf853dadf61d1ad3a�[0m �[33m@astrojs/deno:build: �[0mcache miss, executing �[2m09336b347036f527�[0m �[34m@astrojs/preact:build: �[0mcache miss, executing �[2m1153b555207ada82�[0m �[33m@astrojs/react:build: �[0m �[33m@astrojs/react:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/react �[33m@astrojs/react:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[33m@astrojs/react:build: �[0m �[34m@astrojs/underscore-redirects:build: �[0m �[34m@astrojs/underscore-redirects:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/underscore-redirects �[34m@astrojs/underscore-redirects:build: �[0m> astro-scripts build "src/**/*.ts" && tsc -p tsconfig.json �[34m@astrojs/underscore-redirects:build: �[0m �[36m@astrojs/mdx:build: �[0mcache miss, executing �[2m3b3715bf41c8f64d�[0m �[36m@astrojs/vercel:build: �[0m �[36m@astrojs/vercel:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/vercel �[36m@astrojs/vercel:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[36m@astrojs/vercel:build: �[0m �[35m@astrojs/svelte:build: �[0m �[35m@astrojs/svelte:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/svelte �[35m@astrojs/svelte:build: �[0m> astro-scripts build "src/index.ts" && astro-scripts build "src/editor.cts" --force-cjs --no-clean-dist && tsc �[35m@astrojs/svelte:build: �[0m �[32m@benchmark/timer:build: �[0m �[32m@benchmark/timer:build: �[0m> @benchmark/[email protected] build /home/runner/work/astro/astro/benchmark/packages/timer �[32m@benchmark/timer:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[32m@benchmark/timer:build: �[0m �[33m@astrojs/deno:build: �[0m �[33m@astrojs/deno:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/deno �[33m@astrojs/deno:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[33m@astrojs/deno:build: �[0m �[35m@astrojs/markdoc:build: �[0mcache miss, executing �[2m28e8b08aa3443eac�[0m �[34m@astrojs/preact:build: �[0m �[34m@astrojs/preact:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/preact �[34m@astrojs/preact:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[34m@astrojs/preact:build: �[0m �[36m@astrojs/mdx:build: �[0m �[36m@astrojs/mdx:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/mdx �[36m@astrojs/mdx:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[36m@astrojs/mdx:build: �[0m �[35m@astrojs/markdoc:build: �[0m �[35m@astrojs/markdoc:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/markdoc �[35m@astrojs/markdoc:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[35m@astrojs/markdoc:build: �[0m �[32m@astrojs/rss:build: �[0mcache miss, executing �[2m0d1834a9ae4007d7�[0m �[33m@astrojs/sitemap:build: �[0mcache miss, executing �[2m35d9cd801ac7b0d2�[0m �[34m@astrojs/netlify:build: �[0mcache miss, executing �[2m7e5310fcd29ffb9b�[0m �[36m@astrojs/cloudflare:build: �[0mcache miss, executing �[2mc2421d613777123f�[0m �[32m@astrojs/rss:build: �[0m �[32m@astrojs/rss:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/astro-rss �[32m@astrojs/rss:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[32m@astrojs/rss:build: �[0m �[33m@astrojs/sitemap:build: �[0m �[33m@astrojs/sitemap:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/sitemap �[33m@astrojs/sitemap:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[33m@astrojs/sitemap:build: �[0m �[34m@astrojs/netlify:build: �[0m �[34m@astrojs/netlify:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/netlify �[34m@astrojs/netlify:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[34m@astrojs/netlify:build: �[0m �[36m@astrojs/cloudflare:build: �[0m �[36m@astrojs/cloudflare:build: �[0m> @astrojs/[email protected] build /home/runner/work/astro/astro/packages/integrations/cloudflare �[36m@astrojs/cloudflare:build: �[0m> astro-scripts build "src/**/*.ts" && tsc �[36m@astrojs/cloudflare:build: �[0m Tasks: 30 successful, 30 total Cached: 5 cached, 30 total Time: 1m27.536s 🦋 �[33mwarn�[39m �[31m===============================IMPORTANT!===============================�[39m 🦋 �[33mwarn�[39m Packages will be released under the next--markdoc-config-changes tag 🦋 �[33mwarn�[39m �[31m----------------------------------------------------------------------�[39m 🦋 �[36minfo�[39m npm info astro 🦋 �[36minfo�[39m npm info @astrojs/prism 🦋 �[36minfo�[39m npm info @astrojs/rss 🦋 �[36minfo�[39m npm info create-astro 🦋 �[36minfo�[39m npm info @astrojs/alpinejs 🦋 �[36minfo�[39m npm info @astrojs/cloudflare 🦋 �[36minfo�[39m npm info @astrojs/deno 🦋 �[36minfo�[39m npm info @astrojs/image 🦋 �[36minfo�[39m npm info @astrojs/lit 🦋 �[36minfo�[39m npm info @astrojs/markdoc 🦋 �[36minfo�[39m npm info @astrojs/mdx 🦋 �[36minfo�[39m npm info @astrojs/netlify 🦋 �[36minfo�[39m npm info @astrojs/node 🦋 �[36minfo�[39m npm info @astrojs/partytown 🦋 �[36minfo�[39m npm info @astrojs/preact 🦋 �[36minfo�[39m npm info @astrojs/prefetch 🦋 �[36minfo�[39m npm info @astrojs/react 🦋 �[36minfo�[39m npm info @astrojs/sitemap 🦋 �[36minfo�[39m npm info @astrojs/solid-js 🦋 �[36minfo�[39m npm info @astrojs/svelte 🦋 �[36minfo�[39m npm info @astrojs/tailwind 🦋 �[36minfo�[39m npm info @astrojs/turbolinks 🦋 �[36minfo�[39m npm info @astrojs/vercel 🦋 �[36minfo�[39m npm info @astrojs/vue 🦋 �[36minfo�[39m npm info @astrojs/internal-helpers 🦋 �[36minfo�[39m npm info @astrojs/markdown-component 🦋 �[36minfo�[39m npm info @astrojs/markdown-remark 🦋 �[36minfo�[39m npm info @astrojs/telemetry 🦋 �[36minfo�[39m npm info @astrojs/underscore-redirects 🦋 �[36minfo�[39m npm info @astrojs/webapi 🦋 �[36minfo�[39m astro is being published because our local version (0.0.0-markdoc-config-changes-20230626153541) has not been published on npm 🦋 �[33mwarn�[39m @astrojs/prism is not being published because version 2.1.2 is already published on npm 🦋 �[33mwarn�[39m @astrojs/rss is not being published because version 2.4.3 is already published on npm 🦋 �[33mwarn�[39m create-astro is not being published because version 3.1.8 is already published on npm 🦋 �[33mwarn�[39m @astrojs/alpinejs is not being published because version 0.2.2 is already published on npm 🦋 �[33mwarn�[39m @astrojs/cloudflare is not being published because version 6.5.1 is already published on npm 🦋 �[33mwarn�[39m @astrojs/deno is not being published because version 4.2.0 is already published on npm 🦋 �[33mwarn�[39m @astrojs/image is not being published because version 0.17.1 is already published on npm 🦋 �[33mwarn�[39m @astrojs/lit is not being published because version 2.1.0 is already published on npm 🦋 �[36minfo�[39m @astrojs/markdoc is being published because our local version (0.0.0-markdoc-config-changes-20230626153541) has not been published on npm 🦋 �[33mwarn�[39m @astrojs/mdx is not being published because version 0.19.7 is already published on npm 🦋 �[33mwarn�[39m @astrojs/netlify is not being published because version 2.3.0 is already published on npm 🦋 �[33mwarn�[39m @astrojs/node is not being published because version 5.3.0 is already published on npm 🦋 �[33mwarn�[39m @astrojs/partytown is not being published because version 1.2.3 is already published on npm 🦋 �[33mwarn�[39m @astrojs/preact is not being published because version 2.2.1 is already published on npm 🦋 �[33mwarn�[39m @astrojs/prefetch is not being published because version 0.2.3 is already published on npm 🦋 �[33mwarn�[39m @astrojs/react is not being published because version 2.2.1 is already published on npm 🦋 �[33mwarn�[39m @astrojs/sitemap is not being published because version 1.3.3 is already published on npm 🦋 �[33mwarn�[39m @astrojs/solid-js is not being published because version 2.2.0 is already published on npm 🦋 �[33mwarn�[39m @astrojs/svelte is not being published because version 3.0.0 is already published on npm 🦋 �[33mwarn�[39m @astrojs/tailwind is not being published because version 4.0.0 is already published on npm 🦋 �[33mwarn�[39m @astrojs/turbolinks is not being published because version 0.2.2 is already published on npm 🦋 �[36minfo�[39m @astrojs/vercel is being published because our local version (0.0.0-markdoc-config-changes-20230626153541) has not been published on npm 🦋 �[33mwarn�[39m @astrojs/vue is not being published because version 2.2.1 is already published on npm 🦋 �[36minfo�[39m @astrojs/internal-helpers is being published because our local version (0.0.0-markdoc-config-changes-20230626153541) has not been published on npm 🦋 �[33mwarn�[39m @astrojs/markdown-component is not being published because version 1.0.5 is already published on npm 🦋 �[33mwarn�[39m @astrojs/markdown-remark is not being published because version 2.2.1 is already published on npm 🦋 �[33mwarn�[39m @astrojs/telemetry is not being published because version 2.1.1 is already published on npm 🦋 �[33mwarn�[39m @astrojs/underscore-redirects is not being published because version 0.1.0 is already published on npm 🦋 �[33mwarn�[39m @astrojs/webapi is not being published because version 2.2.0 is already published on npm 🦋 �[36minfo�[39m Publishing �[36m"astro"�[39m at �[32m"0.0.0-markdoc-config-changes-20230626153541"�[39m 🦋 �[36minfo�[39m Publishing �[36m"@astrojs/markdoc"�[39m at �[32m"0.0.0-markdoc-config-changes-20230626153541"�[39m 🦋 �[36minfo�[39m Publishing �[36m"@astrojs/vercel"�[39m at �[32m"0.0.0-markdoc-config-changes-20230626153541"�[39m 🦋 �[36minfo�[39m Publishing �[36m"@astrojs/internal-helpers"�[39m at �[32m"0.0.0-markdoc-config-changes-20230626153541"�[39m 🦋 �[32msuccess�[39m packages published successfully: 🦋 [email protected] 🦋 @astrojs/[email protected] 🦋 @astrojs/[email protected] 🦋 @astrojs/[email protected] 🦋 Creating git tags... 🦋 New tag: [email protected] 🦋 New tag: @astrojs/[email protected] 🦋 New tag: @astrojs/[email protected] 🦋 New tag: @astrojs/[email protected]

[yanthomasdev]

Docs LGTM!