Trouble parsing your MDX frontmatter

Those errors indicate that the TypeScript language server is having trouble parsing your MDX frontmatter in the index.mdx file. This is a common issue with MDX files in TypeScript-enabled projects.

Here’s how to resolve these errors:

src/types/mdx.d.ts

declare module '*.mdx' {
    import type { ComponentType } from 'react';

    export const frontmatter: {
        title?: string;
        description?: string;
        template?: string;
        hero?: string;
        tagline?: string;
        image?: string;
        file?: string;
        actions?: Array<{
            text?: string;
            link?: string;
            icon?: string;
            variant?: string;
        }>;
        [key: string]: any;
    };

    const MDXComponent: ComponentType;

    export default MDXComponent;
}

Now, you’ll need to update your VS Code settings to properly handle MDX files:

{
    "[mdx]": {
        "editor.formatOnSave": false,
        "editor.wordWrap": "on"
    },
    "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact", "astro", "mdx"],
    "files.associations": {
        "*.mdx": "markdown"
    },
    "typescript.enablePromptUseWorkspaceTsdk": true,
    "typescript.tsdk": "node_modules/typescript/lib"
}

You should also add a .astro.d.ts file to help TypeScript understand Astro imports:

/// <reference types="astro/client" />

// Declare components from Starlight that you may use in MDX files
declare module '@astrojs/starlight/components' {
    import type { ComponentType, ReactNode } from 'react';

    export const Tabs: ComponentType<{ children: ReactNode }>;
    export const TabItem: ComponentType<{ label: string; children: ReactNode }>;
    export const Card: ComponentType<{
        title: string;
        icon?: string;
        children: ReactNode;
    }>;
    export const CardGrid: ComponentType<{ children: ReactNode }>;
    export const Steps: ComponentType<{ children: ReactNode }>;
    export const Icon: ComponentType<{ name: string }>;
}

Here’s one more fix to make - create a proper frontmatter schema for Starlight:

import { defineCollection, z } from 'astro:content';
import { docsSchema } from '@astrojs/starlight/schema';

// Create a collection for your docs with a custom schema that extends the Starlight schema
export const collections = {
    docs: defineCollection({
        schema: docsSchema({
            // Add custom frontmatter properties for your docs
            extend: z.object({
                // Example custom frontmatter properties
                hero: z.string().optional(),
                tagline: z.string().optional(),
                image: z
                    .object({
                        file: z.string().optional(),
                    })
                    .optional(),
                actions: z
                    .array(
                        z.object({
                            text: z.string(),
                            link: z.string(),
                            icon: z.string().optional(),
                            variant: z.string().optional(),
                        }),
                    )
                    .optional(),
            }),
        }),
    }),
};

These solutions work together to fix the TypeScript errors in your MDX files:

1. MDX Declaration File - Creates type definitions for MDX files so TypeScript understands the frontmatter format

2. VS Code Settings - Configures your editor to treat MDX files appropriately and use the workspace TypeScript version

3. Astro Type Declarations - Provides type definitions for Astro and Starlight components used in your MDX files

4. Content Schema - Creates a proper schema for your Starlight docs that validates the frontmatter structure

After adding these files to your project:

1. Restart VS Code or reload the window to apply the new settings
2. Restart the TypeScript language server (Ctrl+Shift+P then type “TypeScript: Restart TS server”)
3. Reload any open MDX files to see the errors disappear

This setup properly tells TypeScript how to interpret MDX files and their frontmatter, which should resolve the parsing errors you’re seeing.