Sätteri API Reference

Dodane w: astro@6.4.0

Sätteri is the default Markdown processor in Astro. The @astrojs/markdown-satteri package is optional and can be installed to enable Sätteri-specific features and 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-satteri

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

import {
  createSatteriMarkdownProcessor,
  isSatteriProcessor,
  satteri,
  satteriHeadingIdsPlugin,
} from "@astrojs/markdown-satteri";

createSatteriMarkdownProcessor()

Type: (opts?: SatteriMarkdownProcessorOptions | undefined) => Promise<MarkdownRenderer>

Creates a standalone Sätteri-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 { createSatteriMarkdownProcessor } from "@astrojs/markdown-satteri";

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

isSatteriProcessor()

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

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

The following example checks, within an integration, whether the configured Markdown processor is Sätteri:

src/integrations/my-integration.ts

import { isSatteriProcessor } from "@astrojs/markdown-satteri";
import type { AstroIntegration } from "astro";

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

satteri()

Type: (options?: SatteriProcessorOptions) => MarkdownProcessor

Creates a Sätteri-based Markdown processor to render .md and .mdx files. Pass it to markdown.processor to customize the Markdown rendering behavior.

Learn more about setting up a Markdown processor and using mdast and hast plugins in the Markdown guide.

Options

Type: SatteriProcessorOptions

You can customize the Sätteri processor behavior with the following options.

options.mdastPlugins

Type: MdastPluginList | undefined
Default: []

Pass Sätteri mdast plugins to customize how your Markdown is built.

The following example passes the satteri-emoji plugin to the Sätteri processor:

astro.config.mjs

import { satteri } from "@astrojs/markdown-satteri";
import { satteriEmoji } from "satteri-emoji";

export default {
  markdown: {
    processor: satteri({
      mdastPlugins: [satteriEmoji],
    }),
  },
};

options.hastPlugins

Type: HastPluginList | undefined
Default: []

Pass Sätteri hast plugins to customize how your HTML is generated from the Markdown content.

The following example passes the satteri-custom-header-id plugin to the Sätteri processor:

astro.config.mjs

import { satteri } from "@astrojs/markdown-satteri";
import { satteriCustomHeaderId } from "satteri-custom-header-id";

export default {
  markdown: {
    processor: satteri({
      hastPlugins: [satteriCustomHeaderId],
    }),
  },
};

options.features

Type: SatteriFeatures
Default: {}

Customize the features available in Sätteri.

The following properties use a different default in Astro.

options.features.smartPunctuation

Type: boolean | object
Default: true

Whether to use smart punctuation to convert straight quotes to curly quotes, double hyphens to em dashes, and three dots to ellipses.

You can either disable it or provide a configuration object with the properties supported by Sätteri to customize its behavior.

The following example disables smart punctuation support:

astro.config.mjs

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

export default defineConfig({
  markdown: {
    processor: satteri({
      smartPunctuation: false,
    }),
  },
});

Learn more about configuring smart punctuation in the Markdown guide.

satteriHeadingIdsPlugin()

Type: HastPluginEntry

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.

@astrojs/markdown-satteri types

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

import type {
  SatteriAstroData,
  SatteriMarkdownProcessorOptions,
} from "@astrojs/markdown-satteri";

SatteriAstroData

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

Dodane w: @astrojs/markdown-satteri@0.3.1

Describes the Astro-specific data available in a Sätteri plugin via ctx.data.astro.

SatteriAstroData.frontmatter

Type: Record<string, any>

Contains the properties injected by a plugin into the frontmatter of Markdown or MDX content.

Learn more about modifying the frontmatter programmatically in the Markdown guide.

SatteriAstroData.headings

Type: MarkdownHeading[]

A list of collected headings in the Markdown content.

SatteriAstroData.localImagePaths

Type: Set<string>

An array of local image paths referenced in the Markdown content itself.

SatteriAstroData.remoteImagePaths

Type: Set<string>

An array of remote image paths referenced in the Markdown content itself.

SatteriMarkdownProcessorOptions

Type: AstroMarkdownOptions & { mdastPlugins?: MdastPluginList; hastPlugins?: HastPluginList; features?: SatteriFeatures; }

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

SatteriMarkdownProcessorOptions.mdastPlugins

Type: MdastPluginList

A list of Sätteri mdast plugins to pass to the processor.

SatteriMarkdownProcessorOptions.hastPlugins

Type: HastPluginList

A list of Sätteri hast plugins to pass to the processor.

SatteriMarkdownProcessorOptions.features

Type: SatteriFeatures

Contains the configuration of features to enable or disable in the Sätteri processor.