Syntax Highlighting

/**
 * Create a Shiki syntax highlighter instance
 * @param options - Configuration options for the highlighter
 * @returns Promise resolving to a ShikiHighlighter instance
 */
function createShikiHighlighter(
  options?: CreateShikiHighlighterOptions
): Promise<ShikiHighlighter>;

interface CreateShikiHighlighterOptions {
  /** Array of language registrations to load */
  langs?: LanguageRegistration[];
  /** Default theme or theme registration */
  theme?: ThemePresets | ThemeRegistration | ThemeRegistrationRaw;
  /** Named themes for multi-theme support */
  themes?: Record<string, ThemePresets | ThemeRegistration | ThemeRegistrationRaw>;
  /** Language aliases mapping */
  langAlias?: HighlighterCoreOptions['langAlias'];
}

interface ShikiHighlighter {
  /**
   * Convert code to HAST (HTML AST) tree
   * @param code - Source code to highlight
   * @param lang - Language identifier
   * @param options - Highlighting options
   * @returns Promise resolving to HAST Root node
   */
  codeToHast(
    code: string,
    lang?: string,
    options?: ShikiHighlighterHighlightOptions
  ): Promise<Root>;
  
  /**
   * Convert code to HTML string
   * @param code - Source code to highlight
   * @param lang - Language identifier
   * @param options - Highlighting options
   * @returns Promise resolving to HTML string
   */
  codeToHtml(
    code: string,
    lang?: string,
    options?: ShikiHighlighterHighlightOptions
  ): Promise<string>;
}

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

// Basic highlighter with default settings
const highlighter = await createShikiHighlighter();

// Highlight code to HTML
const htmlResult = await highlighter.codeToHtml(
  'console.log("Hello, world!");',
  'javascript'
);
console.log(htmlResult); // <pre class="astro-code">...</pre>

// Highlight code to HAST tree
const hastResult = await highlighter.codeToHast(
  'const greeting = "Hello";',
  'typescript'
);
console.log(hastResult.children); // HAST nodes

// Advanced highlighter configuration
const advancedHighlighter = await createShikiHighlighter({
  langs: ['javascript', 'typescript', 'python', 'rust'],
  theme: 'material-theme-palenight',
  themes: {
    light: 'github-light',
    dark: 'github-dark',
    hc: 'github-light-high-contrast'
  },
  langAlias: {
    'js': 'javascript',
    'ts': 'typescript',
    'py': 'python'
  }
});

// Using CSS variables theme
const cssVarHighlighter = await createShikiHighlighter({
  theme: 'css-variables',
  langs: ['javascript', 'css']
});

interface ShikiHighlighterHighlightOptions {
  /** Generate inline code element only, without pre wrapper */
  inline?: boolean;
  
  /** 
   * Enable word wrapping
   * - true: enabled
   * - false: disabled  
   * - null: All overflow styling removed
   */
  wrap?: boolean | null;
  
  /** Choose default theme from multi-theme configuration */
  defaultColor?: 'light' | 'dark' | string | false;
  
  /** Shiki transformers to customize generated HTML */
  transformers?: ShikiTransformer[];
  
  /** Additional attributes for root code block element */
  attributes?: Record<string, string>;
  
  /** Raw meta information for transformers */
  meta?: string;
}

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

const highlighter = await createShikiHighlighter({
  themes: {
    light: 'github-light',
    dark: 'github-dark'
  }
});

// Inline code highlighting
const inlineCode = await highlighter.codeToHtml(
  'const x = 5;',
  'javascript',
  { inline: true }
);
// Outputs: <code class="astro-code">...</code>

// Word wrapping enabled
const wrappedCode = await highlighter.codeToHtml(
  'const veryLongVariableName = "This is a very long string that might need wrapping";',
  'javascript',
  { wrap: true }
);

// Multi-theme with default color
const themedCode = await highlighter.codeToHtml(
  'print("Hello, world!")',
  'python',
  { defaultColor: 'dark' }
);

// Custom attributes and meta
const customCode = await highlighter.codeToHtml(
  'function example() {}',
  'javascript',
  {
    attributes: {
      'data-filename': 'example.js',
      'data-line-numbers': 'true'
    },
    meta: 'title="Example Function"'
  }
);

// Custom transformers
const transformedCode = await highlighter.codeToHtml(
  'const highlighted = true;',
  'javascript',
  {
    transformers: [
      {
        pre(node) {
          node.properties.class = 'my-custom-class';
        },
        line(node) {
          // Add line numbers
          node.properties.dataLine = '1';
        }
      }
    ]
  }
);

interface SyntaxHighlightConfig {
  /** Highlighter type */
  type: SyntaxHighlightConfigType;
  /** Languages to exclude from highlighting */
  excludeLangs?: string[];
}

type SyntaxHighlightConfigType = 'shiki' | 'prism';

interface ShikiConfig
  extends Pick<CreateShikiHighlighterOptions, 'langs' | 'theme' | 'themes' | 'langAlias'>,
    Pick<ShikiHighlighterHighlightOptions, 'defaultColor' | 'wrap' | 'transformers'> {}

type ThemePresets = BuiltinTheme | 'css-variables';

// Shiki configuration
const shikiProcessor = await createMarkdownProcessor({
  syntaxHighlight: {
    type: 'shiki',
    excludeLangs: ['math']
  },
  shikiConfig: {
    theme: 'github-dark',
    themes: {
      light: 'github-light',
      dark: 'github-dark'
    },
    wrap: true,
    transformers: []
  }
});

// Prism configuration
const prismProcessor = await createMarkdownProcessor({
  syntaxHighlight: {
    type: 'prism',
    excludeLangs: ['math', 'mermaid']
  }
});

// Disable syntax highlighting
const noHighlightProcessor = await createMarkdownProcessor({
  syntaxHighlight: false
});

// Using CSS variables theme
const cssVarHighlighter = await createShikiHighlighter({
  theme: 'css-variables'
});

.astro-code {
  --astro-code-color-text: #24292e;
  --astro-code-color-background: #ffffff;
  --astro-code-token-constant: #005cc5;
  --astro-code-token-string: #032f62;
  --astro-code-token-comment: #6a737d;
  /* ... more variables */
}