MDX

          
            ## Astro MDX Integration Guidelines

1.  Purpose: Allows using MDX (`.mdx` files) in Astro projects. MDX extends Markdown by allowing JSX expressions, component imports (Astro & UI frameworks), and JavaScript variables directly within content.

2.  Installation: Install using the Astro CLI:

    ```bash
    npx astro add mdx
    # or pnpm add @astrojs/mdx / yarn add @astrojs/mdx
    ```

    This installs the package and adds it to your `astro.config.mjs`.

3.  Usage:

    - Pages: Create `.mdx` files in `src/pages/` just like `.astro` or `.md` files. They will be rendered as pages based on file-based routing.
    - Content Collections: Use `.mdx` files within `src/content/` collections. Query them using `getCollection()` or `getEntryBySlug()`.

4.  Key Features within `.mdx` files:

    - Standard Markdown: All standard Markdown syntax is supported.
    - Frontmatter: Use YAML frontmatter (`---`) just like in `.md` files. Frontmatter variables are accessible via `frontmatter.{variableName}` within the MDX content (after the closing `---`).
    - JSX Expressions: Embed JavaScript expressions directly using curly braces: `<h1>{frontmatter.title}</h1>`, `<p>Calculation: {2 + 2}</p>`.
    - Component Imports: Import Astro (`.astro`) or UI Framework (`.jsx`, `.svelte`, etc.) components using standard `import` statements _below_ the frontmatter.
    - Using Components: Render imported components using JSX syntax: `<MyComponent prop="value" client:load />`. Remember client directives for interactive components.
    - Exporting Variables: Use standard JavaScript `export const myVar = ...;` _below_ the frontmatter to define variables or data within the MDX file. These can be imported by other files.

5.  Rendering MDX Programmatically:

    - When using `getCollection()` or `getEntryBySlug()`, you get access to a `render()` function for the entry.
    - Call `const { Content, headings } = await entry.render();` to get the rendered content.
    - Render the content using the `<Content />` component in an `.astro` file.

6.  Customizing MDX Rendering:

    - `<Content components={...}>`: Pass a `components` prop to the `<Content />` component to override default HTML elements with custom components (e.g., `{ h1: MyCustomHeading }`).
    - Exporting `components` Object: Within an `.mdx` file, `export const components = { h1: MyCustomHeading };` maps Markdown syntax (`# Heading`) directly to your custom component for that file.

7.  Configuration (`astro.config.mjs`): Configure the MDX integration within the `integrations` array.
    - Inheritance: By default (`extendMarkdownConfig: true`), MDX inherits settings from your global `markdown` configuration (e.g., `syntaxHighlight`, `remarkPlugins`, `rehypePlugins`, `gfm`).
    - Overriding: Specify options directly within the `mdx()` config object to override inherited Markdown settings specifically for MDX files (e.g., `mdx({ gfm: false, remarkPlugins: [mdxSpecificPlugin] })`).
    - `extendMarkdownConfig: false`: Set to `false` to completely ignore the global `markdown` config and only use settings defined within `mdx()`.
    - `recmaPlugins`: Add Recma plugins (operate on the JavaScript AST after transformation).
    - `optimize: boolean | { ignoreElementNames?: string[] }`: Experimental optimization for faster builds. May cause issues with custom components passed via the `components` prop unless `ignoreElementNames` is used. Disabled by default.

Reference: [@astrojs/mdx Integration Docs](https://docs.astro.build/en/guides/integrations-guide/mdx/)