Body

Summary

Replace Astro's default Markdown / MDX pipeline with a more performant and lightweight alternative, improving the state of things for the vast majority of users, without losing access to remark / rehype for users that still needs it

Background & Motivation

Bigger Astro websites with a lot of Markdown / MDX files tend to be on the slower side wrt build time, for instance the Astro docs or the Cloudflare docs take multiple minutes to build. The bottleneck is not solely just the Markdown / MDX processing of course, but it's a fair amount of it.

For the past few weeks, I've been working on Sätteri: https://github.com/bruits/satteri, a native Markdown pipeline for the JS ecosystem. The goal is to create a LightningMarkdown to unified's PostCSS. Zero runtime dependencies, extremely fast, low memory usage, but without losing on the ability to use JS plugins, and when using said plugins, have as low of a cost as possible.

I suggest that it could become the default Markdown / MDX pipeline in Astro. Users that do depend on the remark ecosystem / don't / can't port their plugins could still use remark if they prefer, but it would be opt-in.

Goals

• Reduce dependency count (would remove 100+ dependencies)
• Make Astro's handling of content faster and more efficient
• .... without losing in flexibility
• Still possible to opt-in to the remark ecosystem for users who need/prefer it

Example

For Astro users, there are no changes to behavior by default, all of Astro's current features are supported. The same options are supported, althought some properties might have different names now. (ex: it's no longer remarkPlugins).

Authoring plugins

Sätteri uses a subscription-based visitor pattern for plugins. Instead of walking the entire tree in JavaScript, plugins declare which node types they care about, and only those nodes cross the native boundary. The shape of every node matches remark's mdast and rehype's hast respectively, making it easy to port plugins over (by hand or by AI)

MDAST Plugin (remark equivalent)

Before (remark):

import { visit } from "unist-util-visit";

function remarkDemoteHeadings() {
  return (tree) => {
    visit(tree, "heading", (node) => {
      if (node.depth < 6) {
        node.depth++;
      }
    });
  };
}

After (Sätteri):

import { defineMdastPlugin } from "satteri";

const demoteHeadings = defineMdastPlugin({
  name: "demote-headings",
  heading(node, ctx) {
    if (node.depth < 6) {
      ctx.setProperty(node, "depth", node.depth + 1);
    }
  },
});

HAST Plugin (rehype equivalent)

Before (rehype):

import { visit } from "unist-util-visit";

function rehypeAddClassToCodeBlocks() {
  return (tree) => {
    visit(tree, "element", (node) => {
      if (node.tagName === "pre") {
        node.properties.className = ["code-block"];
      }
    });
  };
}

After (Sätteri):

import { defineHastPlugin } from "satteri";

const addClassToCodeBlocks = defineHastPlugin({
  name: "add-class-to-code-blocks",
  element: {
    filter: ["pre"],
    visit(node, ctx) {
      ctx.setProperty(node, "class", "code-block");
    },
  },
});

The filter: ["pre"] means Rust efficiently skips every element that isn't a <pre>, no JS callback fires for other elements in the document. This is similar to the filter property in Rolldown plugins.