Stedefast

Plugins

Plugins Overview

2 min read

Stedefast plugins extend the Markdown processing pipeline at build time. They hook into the unified/remark/rehype chain that processes your .md files into HTML.

Plugins vs. modules

Plugins are build-time only. They transform Markdown content — syntax highlighting, smart quotes, link annotations. They run during Stage 2 (content graph) and produce no runtime code.

Modules add dynamic runtime features — comments, claps, analytics — with server-side persistence and client-side islands.

The StedefastPlugin interface

interface StedefastPlugin {
  name: string;                              // unique name for logging
  remarkPlugins?: PluggableList;             // remark (Markdown AST) plugins
  rehypePlugins?: PluggableList;             // rehype (HTML AST) plugins
  headAssets?: {
    scripts?: string[];                      // <script> tags to inject into <head>
    styles?: string[];                       // <link> tags to inject into <head>
  };
  // runs once after Stage 2 — can write files to outputDir
  buildHook?(ctx: BuildHookContext): Promise<void>;
}

Registering plugins

// stedefast.config.ts
import { defineConfig } from "@stedefast/core";
import { ShikiPlugin } from "/plugin-shiki";

export default defineConfig({
  // ...
  plugins: [
    ShikiPlugin({ theme: "github-dark" }),
  ],
});

Plugins run in the order listed. All remarkPlugins from all registered plugins are applied first, then all rehypePlugins.

The unified pipeline

Stedefast's Markdown pipeline:

.md file
  → remark-parse        (Markdown → AST)
  → remark-frontmatter  (strip YAML front matter)
  → remark-gfm          (GFM tables, task lists, strikethrough)
  → [your remarkPlugins]
  → remark-rehype       (Markdown AST → HTML AST)
  → rehype-slug         (add id= to headings)
  → rehype-autolink-headings
  → [your rehypePlugins]
  → rehype-stringify    (HTML AST → string)

Remark plugins operate on the Markdown AST before conversion to HTML. Rehype plugins operate on the HTML AST after conversion.

Available plugins

Package Purpose
/plugin-shiki Syntax highlighting via Shiki
/plugin-og-images Build-time OG image generation via Satori
/plugin-mermaid Build-time Mermaid diagram rendering to inline SVG
/plugin-reading-progress Lightweight reading progress bar injected as an inline script
/plugin-footnotes GFM footnotes rendered as margin sidenotes on wide screens
/plugin-embeds oEmbed rich embeds (YouTube, Twitter, Gist, CodePen, Spotify, Vimeo)
Edit this page on GitHub