Configuration and Types

/**
 * Configuration options for the MDX integration
 * Extends Astro's markdown configuration with MDX-specific options
 */
export type MdxOptions = Omit<typeof markdownConfigDefaults, 'remarkPlugins' | 'rehypePlugins'> & {
  /** Whether to extend Astro's markdown configuration (default: true) */
  extendMarkdownConfig: boolean;
  
  /** List of recma plugins to apply during compilation */
  recmaPlugins: PluggableList;
  
  /** List of remark plugins (overrides string support from markdown config) */
  remarkPlugins: PluggableList;
  
  /** List of rehype plugins (overrides string support from markdown config) */
  rehypePlugins: PluggableList;
  
  /** Options for remark-rehype transformation */
  remarkRehype: RemarkRehypeOptions;
  
  /** Enable/configure static optimization (default: false) */
  optimize: boolean | OptimizeOptions;
};

/**
 * Complete interface showing all inherited properties from Astro's markdown configuration
 */
interface MdxOptionsExpanded {
  /** Whether to extend Astro's markdown configuration (default: true) */
  extendMarkdownConfig: boolean;
  /** List of recma plugins to apply during compilation */
  recmaPlugins: PluggableList;
  /** List of remark plugins (overrides string support from markdown config) */
  remarkPlugins: PluggableList;
  /** List of rehype plugins (overrides string support from markdown config) */
  rehypePlugins: PluggableList;
  /** Options for remark-rehype transformation */
  remarkRehype: RemarkRehypeOptions;
  /** Enable/configure static optimization (default: false) */
  optimize: boolean | OptimizeOptions;
  
  // Inherited from Astro's markdownConfigDefaults:
  /** Syntax highlighting configuration */
  syntaxHighlight: SyntaxHighlightConfig | SyntaxHighlightConfigType | false;
  /** GitHub Flavored Markdown support */
  gfm: boolean;
  /** Smart typography (quotes, dashes, ellipses) */
  smartypants: boolean;
  /** Shiki syntax highlighter configuration */
  shikiConfig: ShikiConfig;
}

/**
 * Syntax highlighting configuration types
 */
type SyntaxHighlightConfigType = 'shiki' | 'prism';

interface SyntaxHighlightConfig {
  /** Type of syntax highlighter to use */
  type: SyntaxHighlightConfigType;
  /** Languages to exclude from highlighting */
  excludeLangs?: string[];
}

/**
 * Shiki syntax highlighter configuration
 */
interface ShikiConfig {
  /** Languages to include */
  langs?: string[];
  /** Theme name or theme object */
  theme?: string | object;
  /** Multiple themes configuration */
  themes?: Record<string, string | object>;
  /** Language aliases */
  langAlias?: Record<string, string>;
  /** Default color for unstyled text */
  defaultColor?: string | false;
  /** Whether to wrap code in a container */
  wrap?: boolean;
  /** Transformers to apply to highlighted code */
  transformers?: any[];
}

/**
 * Options for remark-rehype transformation
 */
interface RemarkRehypeOptions {
  /** Allow dangerous HTML in markdown */
  allowDangerousHtml?: boolean;
  /** Preserve raw HTML in MDX */
  passThrough?: string[];
  /** Additional options for remark-rehype */
  [key: string]: any;
}

/**
 * Plugin list type supporting various plugin formats
 * Plugin can be a unified plugin function, and Parameters are the plugin options
 */
type PluggableList = Array<Plugin | [Plugin, ...Parameters]>;

/**
 * Generic plugin type for unified processors (remark, rehype, recma)
 */
type Plugin = any; // Plugin functions from unified ecosystem

/**
 * Plugin parameters type for configuration options
 */  
type Parameters = any[];

/**
 * Acorn parser options for JavaScript AST generation
 */
interface AcornOpts {
  /** ECMAScript version to parse */
  ecmaVersion?: 'latest' | number;
  /** Source type for parsing */
  sourceType?: 'module' | 'script';
}

/**
 * MDX ESM AST node representing JavaScript imports/exports
 */
interface MdxjsEsm {
  type: 'mdxjsEsm';
  value: string;
  data: {
    estree: {
      type: 'Program';
      sourceType: 'module';
      body: any[];
    };
  };
}

import mdx from "@astrojs/mdx";
import remarkToc from "remark-toc";
import rehypeSlug from "rehype-slug";

// Basic configuration
const config1: Partial<MdxOptions> = {
  extendMarkdownConfig: true,
  gfm: true,
  smartypants: true,
};

// Advanced plugin configuration
const config2: Partial<MdxOptions> = {
  remarkPlugins: [
    remarkToc,
    [remarkToc, { heading: "Table of Contents" }],
  ],
  rehypePlugins: [
    rehypeSlug,
    [rehypeAutolinkHeadings, { behavior: "wrap" }],
  ],
  recmaPlugins: [],
};

// Optimization configuration
const config3: Partial<MdxOptions> = {
  optimize: {
    ignoreElementNames: ["CustomComponent", "DynamicWidget"],
  },
};

/**
 * Options for optimizing static content in MDX
 */
interface OptimizeOptions {
  /** 
   * Element names to exclude from static optimization
   * These elements will remain as JSX for dynamic rendering
   */
  ignoreElementNames?: string[];
}

// Enable basic optimization
const basicOptimize: MdxOptions['optimize'] = true;

// Customize optimization behavior
const customOptimize: OptimizeOptions = {
  ignoreElementNames: [
    "InteractiveChart",
    "DynamicForm", 
    "LiveCounter"
  ],
};

// Use in MDX config
export default defineConfig({
  integrations: [
    mdx({
      optimize: customOptimize,
    }),
  ],
});

/**
 * Configuration for the internal Vite MDX plugin
 */
export interface VitePluginMdxOptions {
  /** Resolved MDX configuration options */
  mdxOptions: MdxOptions;
  /** Source directory URL */
  srcDir: URL;
  /** Experimental heading ID compatibility mode */
  experimentalHeadingIdCompat: boolean;
}

/**
 * File information structure used in processing
 */
interface FileInfo {
  /** File identifier path */
  fileId: string;
  /** File URL for web access */
  fileUrl: string;
}

/**
 * Container renderer configuration
 */
interface ContainerRenderer {
  /** Renderer name identifier */
  name: string;
  /** Server entrypoint module path */
  serverEntrypoint: string;
}

// Inherited properties
interface InheritedMarkdownConfig {
  syntaxHighlight: SyntaxHighlightConfig | SyntaxHighlightConfigType | false;
  gfm: boolean;
  smartypants: boolean;
  remarkPlugins: PluggableList;
  rehypePlugins: PluggableList;
  shikiConfig: ShikiConfig;
  remarkRehype: RemarkRehypeOptions;
}

const defaultMdxOptions: Partial<MdxOptions> = {
  extendMarkdownConfig: true,
  recmaPlugins: [],
  optimize: false,
};

// Built-in remark plugins (when enabled)
- remarkGfm: GitHub Flavored Markdown
- remarkSmartypants: Smart typography  
- remarkCollectImages: Image processing for Astro

// Custom plugins
remarkPlugins: [
  remarkToc,                    // Simple plugin
  [remarkMath, { strict: false }], // Plugin with options
]

// Built-in rehype plugins
- rehypeMetaString: Preserve meta information
- rehypeRaw: Allow raw HTML with MDX
- rehypeShiki/rehypePrism: Syntax highlighting
- rehypeHeadingIds: Generate heading IDs
- rehypeImageToComponent: Convert images to Astro Image components

// Custom plugins  
rehypePlugins: [
  rehypeSlug,
  [rehypeAutolinkHeadings, { behavior: "wrap" }],
]

// Usually empty by default
recmaPlugins: [
  // Custom JavaScript transformations
]

// Development configuration
const devConfig: Partial<MdxOptions> = {
  optimize: false, // Faster builds
  syntaxHighlight: 'prism', // Lighter bundle
};

// Production configuration  
const prodConfig: Partial<MdxOptions> = {
  optimize: true, // Better performance
  syntaxHighlight: 'shiki', // Better highlighting
};

export default defineConfig({
  integrations: [
    mdx(import.meta.env.DEV ? devConfig : prodConfig),
  ],
});

// Reusable plugin configurations
const mathPlugins = [
  remarkMath,
  [rehypeMathjax, { tex: { displayMath: [["$$", "$$"]] } }],
];

const documentationPlugins = [
  remarkToc,
  rehypeSlug,
  [rehypeAutolinkHeadings, { behavior: "wrap" }],
];

export default defineConfig({
  integrations: [
    mdx({
      remarkPlugins: [...mathPlugins, ...documentationPlugins],
    }),
  ],
});