or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

frontmatter.mdindex.mdmarkdown-processing.mdrehype-plugins.mdremark-plugins.mdsyntax-highlighting.md
tile.json

tessl/npm-astrojs--markdown-remark

Astro's internal markdown processing library that provides a unified markdown processor built on remark and rehype ecosystem plugins with syntax highlighting, frontmatter parsing, and image processing capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@astrojs/markdown-remark@6.3.x

To install, run

npx @tessl/cli install tessl/npm-astrojs--markdown-remark@6.3.0

index.mddocs/

@astrojs/markdown-remark

Astro's internal markdown processing library that provides a unified markdown processor built on remark and rehype ecosystem plugins. It supports syntax highlighting with Shiki and Prism, frontmatter parsing, image processing, heading collection, and extensive plugin customization.

Package Information

  • Package Name: @astrojs/markdown-remark
  • Package Type: npm
  • Language: TypeScript
  • Installation: This package is typically used as part of Astro's build system. Install Astro: npm install astro

Core Imports

import { 
  createMarkdownProcessor, 
  markdownConfigDefaults, 
  syntaxHighlightDefaults,
  defaultExcludeLanguages,
  parseFrontmatter,
  extractFrontmatter,
  isFrontmatterValid,
  createShikiHighlighter,
  rehypeHeadingIds,
  rehypePrism,
  rehypeShiki,
  rehypeImages,
  remarkCollectImages
} from "@astrojs/markdown-remark";

For CommonJS:

const { 
  createMarkdownProcessor, 
  markdownConfigDefaults, 
  syntaxHighlightDefaults,
  defaultExcludeLanguages,
  parseFrontmatter,
  extractFrontmatter,
  isFrontmatterValid,
  createShikiHighlighter,
  rehypeHeadingIds,
  rehypePrism,
  rehypeShiki,
  rehypeImages,
  remarkCollectImages
} = require("@astrojs/markdown-remark");

Basic Usage

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

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

// Process markdown content
const result = await processor.render("# Hello World\n\nThis is **bold** text.");
console.log(result.code); // HTML output
console.log(result.metadata.headings); // Extracted headings

Architecture

@astrojs/markdown-remark is built around several key components:

  • Unified Pipeline: Uses the unified ecosystem (remark → rehype) for markdown processing
  • Syntax Highlighting: Dual support for Shiki and Prism highlighters with extensive configuration
  • Frontmatter Processing: YAML and TOML frontmatter parsing with multiple handling modes
  • Plugin System: Extensible plugin architecture supporting both remark and rehype plugins
  • Image Processing: Automatic collection and processing of local and remote images
  • Heading Management: Automatic ID generation and metadata collection for headings

Capabilities

Markdown Processing

Core markdown processing functionality that transforms markdown content into HTML using a unified processing pipeline.

function createMarkdownProcessor(
  opts?: AstroMarkdownProcessorOptions
): Promise<MarkdownProcessor>;

interface MarkdownProcessor {
  render: (
    content: string,
    opts?: MarkdownProcessorRenderOptions
  ) => Promise<MarkdownProcessorRenderResult>;
}

const markdownConfigDefaults: Required<AstroMarkdownOptions>;
const syntaxHighlightDefaults: Required<SyntaxHighlightConfig>;

/**
 * Default languages excluded from syntax highlighting
 * Currently excludes: ['math']
 */
const defaultExcludeLanguages: string[];

Markdown Processing

Frontmatter Processing

Comprehensive frontmatter parsing with support for YAML and TOML formats, including validation and flexible content handling.

function parseFrontmatter(
  code: string,
  options?: ParseFrontmatterOptions
): ParseFrontmatterResult;

function extractFrontmatter(code: string): string | undefined;

function isFrontmatterValid(frontmatter: Record<string, any>): boolean;

interface ParseFrontmatterOptions {
  frontmatter: 'preserve' | 'remove' | 'empty-with-spaces' | 'empty-with-lines';
}

interface ParseFrontmatterResult {
  frontmatter: Record<string, any>;
  rawFrontmatter: string;
  content: string;
}

Frontmatter Processing

Syntax Highlighting

Advanced syntax highlighting with Shiki and Prism support, including custom themes, language aliases, and code transformers.

function createShikiHighlighter(
  options?: CreateShikiHighlighterOptions
): Promise<ShikiHighlighter>;

interface ShikiHighlighter {
  codeToHast(
    code: string,
    lang?: string,
    options?: ShikiHighlighterHighlightOptions
  ): Promise<Root>;
  codeToHtml(
    code: string,
    lang?: string,
    options?: ShikiHighlighterHighlightOptions
  ): Promise<string>;
}

Syntax Highlighting

Rehype Plugins

Built-in rehype plugins for heading processing, image optimization, and syntax highlighting integration.

function rehypeHeadingIds(options?: {
  experimentalHeadingIdCompat?: boolean;
}): ReturnType<RehypePlugin>;

const rehypePrism: Plugin<[string[]?], Root>;
const rehypeShiki: Plugin<[ShikiConfig, string[]?], Root>;
function rehypeImages(): Plugin<[], Root>;

Rehype Plugins

Remark Plugins

Built-in remark plugins for image collection and other content processing tasks.

function remarkCollectImages(
  opts?: AstroMarkdownProcessorOptions['image']
): Plugin<[AstroMarkdownProcessorOptions['image']?], mdast.Root>;

Remark Plugins

Configuration Constants

Pre-defined constants for syntax highlighting configuration.

/**
 * Default languages excluded from syntax highlighting
 * Currently excludes: ['math']
 */
const defaultExcludeLanguages: string[];

Usage Examples:

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

// Use default exclude list
const processor = await createMarkdownProcessor({
  syntaxHighlight: {
    type: 'shiki',
    excludeLangs: defaultExcludeLanguages
  }
});

// Extend default exclude list
const extendedExcludeList = [...defaultExcludeLanguages, 'mermaid', 'graphql'];
const processorExtended = await createMarkdownProcessor({
  syntaxHighlight: {
    type: 'shiki',
    excludeLangs: extendedExcludeList
  }
});

console.log(defaultExcludeLanguages); // ['math']

Types

Core types used across the package:

interface AstroMarkdownOptions {
  syntaxHighlight?: SyntaxHighlightConfig | SyntaxHighlightConfigType | false;
  shikiConfig?: ShikiConfig;
  remarkPlugins?: RemarkPlugins;
  rehypePlugins?: RehypePlugins;
  remarkRehype?: RemarkRehype;
  gfm?: boolean;
  smartypants?: boolean;
}

interface AstroMarkdownProcessorOptions extends AstroMarkdownOptions {
  image?: {
    domains?: string[];
    remotePatterns?: RemotePattern[];
  };
  experimentalHeadingIdCompat?: boolean;
}

interface MarkdownProcessorRenderOptions {
  fileURL?: URL;
  frontmatter?: Record<string, any>;
}

interface MarkdownProcessorRenderResult {
  code: string;
  metadata: {
    headings: MarkdownHeading[];
    localImagePaths: string[];
    remoteImagePaths: string[];
    frontmatter: Record<string, any>;
  };
}

interface MarkdownHeading {
  depth: number;
  slug: string;
  text: string;
}

interface SyntaxHighlightConfig {
  type: SyntaxHighlightConfigType;
  excludeLangs?: string[];
}

type SyntaxHighlightConfigType = 'shiki' | 'prism';

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

type RemarkPlugins = (string | [string, any] | RemarkPlugin | [RemarkPlugin, any])[];
type RehypePlugins = (string | [string, any] | RehypePlugin | [RehypePlugin, any])[];

type RemarkPlugin<PluginParameters extends any[] = any[]> = unified.Plugin<
  PluginParameters,
  mdast.Root
>;

type RehypePlugin<PluginParameters extends any[] = any[]> = unified.Plugin<
  PluginParameters,
  hast.Root
>;

type ThemePresets = BuiltinTheme | 'css-variables';
type RemarkRehype = RemarkRehypeOptions;
type Node = unist.Node;

interface RemotePattern {
  protocol?: string;
  hostname?: string;
  port?: string;
  pathname?: string;
}

interface CreateShikiHighlighterOptions {
  langs?: LanguageRegistration[];
  theme?: ThemePresets | ThemeRegistration | ThemeRegistrationRaw;
  themes?: Record<string, ThemePresets | ThemeRegistration | ThemeRegistrationRaw>;
  langAlias?: Record<string, string>;
}

interface ShikiHighlighterHighlightOptions {
  inline?: boolean;
  wrap?: boolean | null;
  defaultColor?: 'light' | 'dark' | string | false;
  transformers?: ShikiTransformer[];
  attributes?: Record<string, string>;
  meta?: string;
}

// External types from dependencies
type BuiltinTheme = string; // From 'shiki'
type LanguageRegistration = any; // From 'shiki'
type ThemeRegistration = any; // From 'shiki'
type ThemeRegistrationRaw = any; // From 'shiki'
type ShikiTransformer = any; // From 'shiki'
type RemarkRehypeOptions = any; // From 'remark-rehype'
type Root = any; // From 'hast'
type Plugin<T extends any[] = any[], U = any> = any; // From 'unified'

// AST type namespaces
namespace hast {
  type Root = any; // HTML AST root
}
namespace mdast {
  type Root = any; // Markdown AST root
}
namespace unist {
  type Node = any; // Universal AST node
}