0004: MDX components without imports

Context#

MDX lets a record embed a component, for example a callout, a decision matrix or an embedded diagram viewer. In plain MDX every file has to import the component, with a relative path that depends on how deep the file sits in decisions/. Authors copy the import wrong, and a renamed component breaks dozens of records.

Decision#

The mdxComponents option names one module whose default export maps component names to components. The app passes that map to every rendered MDX file: records, project intros, pages in pagesDir and _landing.mdx. Inside those files the names are available as JSX tags with no import.

How to use it#

1
export default defineConfig({
2
  mdxComponents: './components/mdx.ts',
3
});

The module#

1
import Callout from './Callout.astro';
2

3
/** Components available in every .mdx record and page without importing them. */
4
export default { Callout };

1
---
2
interface Props { title?: string }
3
const { title = 'Note' } = Astro.props;
4
---
5
<aside class="callout" role="note">
6
  <strong>{title}</strong>
7
  <slot />
8
</aside>
9

10
<style>
11
  .callout { margin: 1.5rem 0; padding: 1rem 1.25rem; border-left: 3px solid var(--inkan-accent); border-radius: var(--inkan-radius); background: var(--inkan-surface); }
12
  .callout strong { display: block; margin-bottom: 0.25rem; }
13
</style>

Using a component#

1
---
2
title: On-call for decisions
3
description: Who to ask when a record is unclear.
4
---
5

6
Every project folder has owners in its `_project.yml`.
7

8
<Callout title="Escalation">
9
  No owner within a day? Post in #architecture and tag the Platform Engineering lead.
10
</Callout>

The same works in decisions/<project>/adr/0007-something.mdx. Records may be .md or .mdx; the type and number come from the folder and file name either way.

Replacing HTML elements#

The map can also override the components MDX uses for plain Markdown elements, which is standard MDX behaviour. Keys are lowercase tag names:

1
import Callout from './Callout.astro';
2
import Table from './Table.astro';
3

4
export default { Callout, table: Table };

Every table in every MDX file then renders through Table.astro. Markdown (.md) files are not affected.

Where it applies#

Edits to the module or to a component hot-reload in the dev server. Changing the mdxComponents path itself restarts it.

Consequences#

• Authors write <Callout> and nothing else. Renaming or moving a component is a one-line change in mdx.ts.
• Components are only available in MDX. Teams that write .md keep plain Markdown and the GitHub-flavoured extras.
• The whole map is loaded for every MDX page. A component with heavy dependencies slows every build, even when few records use it.
• MDX files render on GitHub and GitLab as plain text with unknown tags; the component content is still readable there, the frame is not.