Markdown Processing

/**
 * Creates a markdown preprocessor to render multiple markdown files
 * @param opts - Optional configuration for the processor
 * @returns Promise resolving to a MarkdownProcessor instance
 */
function createMarkdownProcessor(
  opts?: AstroMarkdownProcessorOptions
): Promise<MarkdownProcessor>;

interface MarkdownProcessor {
  /**
   * Renders markdown content to HTML with metadata extraction
   * @param content - The markdown content to process
   * @param opts - Optional rendering options
   * @returns Promise resolving to rendered HTML and metadata
   */
  render: (
    content: string,
    opts?: MarkdownProcessorRenderOptions
  ) => Promise<MarkdownProcessorRenderResult>;
}

import { createMarkdownProcessor } from "@astrojs/markdown-remark";

// Create processor with default settings
const processor = await createMarkdownProcessor();

// Create processor with custom configuration
const customProcessor = await createMarkdownProcessor({
  syntaxHighlight: { type: 'shiki', excludeLangs: ['plaintext'] },
  gfm: true,
  smartypants: true,
  remarkPlugins: ['remark-math'],
  rehypePlugins: [['rehype-katex', { strict: false }]],
  shikiConfig: {
    theme: 'github-dark',
    wrap: true
  }
});

// Process markdown with frontmatter
const result = await processor.render(`---
title: "My Document"
tags: ["markdown", "demo"]
---

# Hello World

This is **bold** text with \`inline code\`.

\`\`\`javascript
console.log("Hello, world!");
\`\`\`

![Image](./image.png)
`);

console.log(result.code); // HTML output
console.log(result.metadata.frontmatter); // { title: "My Document", tags: [...] }
console.log(result.metadata.headings); // [{ depth: 1, slug: "hello-world", text: "Hello World" }]
console.log(result.metadata.localImagePaths); // ["./image.png"]

/**
 * Default configuration for markdown processing
 */
const markdownConfigDefaults: Required<AstroMarkdownOptions>;

/**
 * Default configuration for syntax highlighting
 */
const syntaxHighlightDefaults: Required<SyntaxHighlightConfig>;

import { markdownConfigDefaults, syntaxHighlightDefaults } from "@astrojs/markdown-remark";

// Use defaults as base for custom configuration
const customConfig = {
  ...markdownConfigDefaults,
  gfm: false,
  remarkPlugins: [...markdownConfigDefaults.remarkPlugins, 'remark-math']
};

// Check default syntax highlighting settings
console.log(syntaxHighlightDefaults.type); // 'shiki'
console.log(syntaxHighlightDefaults.excludeLangs); // ['math']

interface MarkdownProcessorRenderOptions {
  /** Internal file URL for error reporting and source mapping */
  fileURL?: URL;
  /** Used for frontmatter injection plugins */
  frontmatter?: Record<string, any>;
}

interface MarkdownProcessorRenderResult {
  /** Rendered HTML content */
  code: string;
  /** Extracted metadata from the markdown processing */
  metadata: {
    /** List of headings with IDs and text content */
    headings: MarkdownHeading[];
    /** Array of local image paths found in the document */
    localImagePaths: string[];
    /** Array of remote image URLs found in the document */
    remoteImagePaths: string[];
    /** Parsed frontmatter object */
    frontmatter: Record<string, any>;
  };
}

interface MarkdownHeading {
  /** Heading level (1-6) */
  depth: number;
  /** Generated slug for the heading ID */
  slug: string;
  /** Text content of the heading */
  text: string;
}

interface AstroMarkdownOptions {
  /** Syntax highlighting configuration */
  syntaxHighlight?: SyntaxHighlightConfig | SyntaxHighlightConfigType | false;
  /** Shiki-specific configuration options */
  shikiConfig?: ShikiConfig;
  /** Array of remark plugins to apply */
  remarkPlugins?: RemarkPlugins;
  /** Array of rehype plugins to apply */
  rehypePlugins?: RehypePlugins;
  /** Options passed to remark-rehype */
  remarkRehype?: RemarkRehype;
  /** Enable GitHub Flavored Markdown support */
  gfm?: boolean;
  /** Enable SmartyPants typography enhancements */
  smartypants?: boolean;
}

interface AstroMarkdownProcessorOptions extends AstroMarkdownOptions {
  /** Image processing configuration */
  image?: {
    /** Allowed domains for remote images */
    domains?: string[];
    /** Remote patterns for image validation */
    remotePatterns?: RemotePattern[];
  };
  /** Enable experimental heading ID compatibility mode */
  experimentalHeadingIdCompat?: boolean;
}

import { createMarkdownProcessor } from "@astrojs/markdown-remark";

// Advanced configuration example
const processor = await createMarkdownProcessor({
  // Syntax highlighting with Shiki
  syntaxHighlight: {
    type: 'shiki',
    excludeLangs: ['math', 'mermaid']
  },
  
  // Shiki configuration
  shikiConfig: {
    theme: 'material-theme-palenight',
    themes: {
      light: 'github-light',
      dark: 'github-dark'
    },
    wrap: true,
    transformers: [
      // Custom transformers for code blocks
    ],
    langAlias: {
      'js': 'javascript',
      'ts': 'typescript'
    }
  },
  
  // Plugin configuration
  remarkPlugins: [
    'remark-math',
    ['remark-toc', { tight: true }]
  ],
  rehypePlugins: [
    'rehype-katex',
    ['rehype-autolink-headings', { behavior: 'wrap' }]
  ],
  
  // Image configuration
  image: {
    domains: ['example.com', 'cdn.example.com'],
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.githubusercontent.com'
      }
    ]
  },
  
  // Other options
  gfm: true,
  smartypants: true,
  experimentalHeadingIdCompat: false
});