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.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@astrojs/markdown-remark

Name: tessl/npm-astrojs--markdown-remark
Author: tessl

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
}