Unified API Reference

Astro offers optional support for unified, a popular Markdown ecosystem, via the @astrojs/markdown-remark package. This allows you to customize and extend the rendering process using remark and rehype plugins. It also provides a set of helpers and types helpful when building integrations or plugins.

For features and usage examples, see Markdown processors in the Markdown guide.

Imports from @astrojs/markdown-remark

The following helpers are imported from @astrojs/markdown-remark:

import {
  createMarkdownProcessor,
  isUnifiedProcessor,
  parseFrontmatter,
  rehypeHeadingIds,
  unified,
} from "@astrojs/markdown-remark";

createMarkdownProcessor()

Type: (opts?: AstroMarkdownOptions) => Promise<MarkdownRenderer>

新增於： @astrojs/markdown-remark@3.2.0

Creates a standalone unified-based Markdown renderer. This is useful when you need to render Markdown independently of a project’s configured markdown.processor.

src/utils/markdown.ts

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

const processor = await createMarkdownProcessor();
const { code, metadata } = await processor.render("# Hello world");

isUnifiedProcessor()

Type: (p: { name: string; }) => boolean

新增於： @astrojs/markdown-remark@7.2.0

Determines whether the given Markdown processor is unified. This is useful when you need to check the type of a processor before applying unified-specific logic.

The following example checks, within an integration, whether the configured Markdown processor is unified:

src/integrations/my-integration.ts

import { isUnifiedProcessor } from "@astrojs/markdown-remark";
import type { AstroIntegration } from "astro";

export default function myIntegration(): AstroIntegration {
  return {
    name: "my-integration",
    hooks: {
      "astro:config:done": ({ config }) => {
        if (isUnifiedProcessor(config.markdown.processor)) {
          // Apply unified-specific logic here
        }
      },
    },
  };
}

rehypeHeadingIds()

Type: RehypePlugin

新增於： @astrojs/markdown-remark@1.2.0

Generates and collects heading IDs for all headings in the Markdown content. This makes them available when importing or rendering Markdown content.

See heading IDs and plugins in the Markdown guide for usage example.

unified()

Type: (options?: UnifiedProcessorOptions) => MarkdownProcessor

新增於： @astrojs/markdown-remark@7.2.0

Creates a unified-based processor to render .md and .mdx files. Pass it to markdown.processor to use unified as the default Markdown processor.

Learn more about setting up a Markdown processor and using remark and rehype plugins with examples.

Options

Type: UnifiedProcessorOptions

You can customize the unified processor behavior with the following options.

options.remarkPlugins

Type: RemarkPlugins
Default: []

Pass remark plugins to customize how your Markdown is built. You can import and apply the plugin function (recommended), or pass the plugin name as a string.

The following example passes the remark-toc plugin, with a custom heading option, to the unified processor:

astro.config.mjs

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import remarkToc from "remark-toc";

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [[remarkToc, { heading: "contents" }]],
    }),
  },
});

options.rehypePlugins

Type: RehypePlugins
Default: []

Pass rehype plugins to customize how your HTML is generated from the Markdown content. You can import and apply the plugin function (recommended), or pass the plugin name as a string.

The following example passes the rehype-accessible-emojis plugin to the unified processor:

astro.config.mjs

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import { rehypeAccessibleEmojis } from "rehype-accessible-emojis";

export default defineConfig({
  markdown: {
    processor: unified({
      rehypePlugins: [rehypeAccessibleEmojis],
    }),
  },
});

options.remarkRehype

Type: RemarkRehype

Pass options to the remark-rehype plugin to control how Markdown is transformed into HTML.

The following example customizes the footnote labels:

astro.config.mjs

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";

export default defineConfig({
  markdown: {
    processor: unified({
      remarkRehype: {
        footnoteLabel: "Footnotes",
        footnoteBackLabel: "Back to reference 1",
      },
    }),
  },
});

options.recmaPlugins

Type: PluggableList
Default: []

Pass recma plugins to customize the estree output of your MDX files. This is useful for modifying or injecting JavaScript variables.

astro.config.mjs

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import myRecmaPlugin from "./my-recma-plugin.mjs";

export default defineConfig({
  markdown: {
    processor: unified({
      recmaPlugins: [myRecmaPlugin],
    }),
  },
});

You can use AST Explorer to play with estree outputs, and try estree-util-visit for searching across JavaScript nodes.

options.gfm

Type: boolean
Default: true

Whether to enable or disable GitHub-flavored Markdown (GFM) support.

To disable this, set the gfm option to false:

astro.config.mjs

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";

export default defineConfig({
  markdown: {
    processor: unified({
      gfm: false,
    }),
  },
});

Learn more about using GitHub Flavored Markdown in Astro.

options.smartypants

Type: boolean | Smartypants
Default: true

Whether to use the SmartyPants formatter to transform straight quotes into smart quotes, dashes into en/em dashes, and triple dots into ellipses.

You can either disable it or provide a configuration object with the properties supported by retext-smartypants to customize its behavior.

The following example disables smart punctuation support:

astro.config.mjs

import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";

export default defineConfig({
  markdown: {
    processor: unified({
      smartypants: false,
    }),
  },
});

Learn more about configuring smart punctuation in the Markdown guide.

@astrojs/markdown-remark types

The following types are imported from @astrojs/markdown-remark:

import type {
  AstroMarkdownOptions,
  MarkdownHeading,
  MarkdownProcessor,
  MarkdownRenderOptions,
  MarkdownRenderResult,
  MarkdownRenderer,
  RehypePlugin,
  RehypePlugins,
  RemarkPlugin,
  RemarkPlugins,
  RemarkRehype,
  ShikiConfig,
  Smartypants,
  SyntaxHighlightConfig,
  SyntaxHighlightConfigType,
} from "@astrojs/markdown-remark";

AstroMarkdownOptions

Type: { syntaxHighlight?: SyntaxHighlightConfig | SyntaxHighlightConfigType | false; shikiConfig?: ShikiConfig; image?: { domains?: string[]; remotePatterns?: RemotePattern[]; }; }

新增於： @astrojs/markdown-remark@7.2.0

Describes the Markdown processor configuration. This contains all the markdown options plus the following.

AstroMarkdownOptions.image

Type: { domains?: string[]; remotePatterns?: RemotePattern[]; }

Specifies the image configuration for the Markdown processor.

AstroMarkdownOptions.image.domains

Type: string[]

See image.domains in the configuration reference.

AstroMarkdownOptions.image.remotePatterns

Type: RemotePattern[]

See image.remotePatterns in the configuration reference.

MarkdownHeading

Type: { depth: number; slug: string; text: string; }

新增於： @astrojs/markdown-remark@7.2.0

Represents a heading in a Markdown or MDX document.

MarkdownHeading.depth

Type: number

The heading level, from 1 (<h1>) to 6 (<h6>).

MarkdownHeading.slug

Type: string

Specifies the generated slug used as the id attribute for anchor links.

MarkdownHeading.text

Type: string

Contains the heading’s rendered text content.

MarkdownProcessor

Type: object

新增於： @astrojs/markdown-remark@7.2.0

Describes the configured markdown.processor. This is useful when you want to indicate that a variable accepts any built-in Markdown processor.

MarkdownRenderOptions

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

新增於： @astrojs/markdown-remark@7.2.0

Describes the options available when rendering Markdown content.

MarkdownRenderOptions.fileURL

Type: URL

Specifies the URL of the Markdown file being rendered.

MarkdownRenderOptions.frontmatter

Type: Record<string, any>

Provides the frontmatter data for the Markdown content.

MarkdownRenderResult

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

新增於： @astrojs/markdown-remark@7.2.0

Describes a rendered Markdown file.

MarkdownRenderResult.code

Type: string

Contains the rendered HTML code.

MarkdownRenderResult.metadata

Type: { headings: MarkdownHeading[]; localImagePaths: string[]; remoteImagePaths: string[]; frontmatter: Record<string, any>; }

Describes the metadata associated with the rendered content.

MarkdownRenderResult.metadata.headings

Type: MarkdownHeading[]

A list of extracted headings.

MarkdownRenderResult.metadata.localImagePaths

Type: string[]

An array of local image paths referenced in the rendered content.

MarkdownRenderResult.metadata.remoteImagePaths

Type: string[]

An array of remote image paths referenced in the rendered content.

MarkdownRenderResult.metadata.frontmatter

Type: Record<string, any>

The frontmatter passed to the renderer.

MarkdownRenderer

Type: { render: (content: string, opts?: MarkdownRenderOptions) => Promise<MarkdownRenderResult>; }

新增於： @astrojs/markdown-remark@7.2.0

Specifies the interface implemented by a standalone Markdown processor.

MarkdownRenderer.render()

Type: (content: string, opts?: MarkdownRenderOptions) => Promise<MarkdownRenderResult>

Generates the rendered HTML and metadata for the given Markdown content. You can customize the rendering process using options as second argument.

RehypePlugin

Type: Plugin<PluginParameters, HastRoot>

新增於： @astrojs/markdown-remark@7.2.0

Defines a rehype plugin in the unified ecosystem.

RehypePlugins

Type: (string | [string, any] | RehypePlugin | [RehypePlugin, any])[]

新增於： @astrojs/markdown-remark@7.2.0

A list of rehype plugins to customize the HTML output generated from Markdown content. Each entry is either an imported plugin or the package name that Astro should automatically import.

RemarkPlugin

Type: Plugin<PluginParameters, MdastRoot>

新增於： @astrojs/markdown-remark@7.2.0

Defines a remark plugin in the unified ecosystem.

RemarkPlugins

Type: (string | [string, any] | RemarkPlugin | [RemarkPlugin, any])[]

新增於： @astrojs/markdown-remark@7.2.0

A list of remark plugins to customize the Markdown processing. Each entry is either an imported plugin or the package name that Astro should automatically import.

RemarkRehype

Type: Record<string, unknown>

新增於： @astrojs/markdown-remark@7.2.0

Specifies the options passed to the remark-rehype plugin.

ShikiConfig

Type: object

新增於： @astrojs/markdown-remark@7.2.0

Describes the options to configure the Shiki syntax highlighter.

Learn more about syntax highlighting with example usage.

ShikiConfig.langs

Type: LanguageRegistration[]

A list of Shiki languages to enable in the syntax highlighter.

ShikiConfig.langAlias

Type: Record<string, string>

Defines custom aliases to map to a Shiki language ID.

See Shiki language aliases for more information.

ShikiConfig.theme

Type: ThemePresets | ThemeRegistration | ThemeRegistrationRaw

Specifies the default theme for syntax highlighting. This can be a Shiki bundled theme or a custom Shiki theme.

Learn more about setting a default Shiki theme with example usage.

ShikiConfig.themes

Type: Record<string, ThemePresets | ThemeRegistration | ThemeRegistrationRaw>

An object mapping theme names to their corresponding Shiki theme configurations.

Learn how to set dark and light themes with example usage.

ShikiConfig.defaultColor

Type: 'light' | 'dark' | string | false

Specifies the default theme to use when [ShikiConfig.themes] is defined.

ShikiConfig.wrap

Type: boolean | null

Whether to prevent horizontal scrolling by wrapping long lines.

ShikiConfig.transformers

Type: ShikiTransformer[]

A list of Shiki transformers to customize the generated HTML.

Learn how to apply transformers to <Code /> when you only need them for specific code blocks.

Smartypants

Type: object

新增於： @astrojs/markdown-remark@7.2.0

Describes the configuration options for retext-smartypants.

Learn more about using smart punctuation in Astro.

SyntaxHighlightConfig

Type: { type: SyntaxHighlightConfigType; excludeLangs?: string[]; }

新增於： @astrojs/markdown-remark@7.2.0

Specifies the configured syntax highlighter and the languages to exclude from highlighting.

Learn more about using syntax highlighting with example usage.

SyntaxHighlightConfigType

Type: 'shiki' | 'prism'

新增於： @astrojs/markdown-remark@7.2.0

A union of supported syntax highlighter in Astro.