Satteri Image Attributes

A Satteri HAST plugin that adds attributes with a second set of parentheses:

![Alt text](./photo.jpg)(width: 640, loading: lazy)

Install

pnpm add satteri-imgattr

Astro

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

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

When @astrojs/mdx is installed, it inherits this Satteri configuration for the Markdown parts of .mdx files. The plugin therefore handles ![alt](image.jpg)(width: 640) in MDX, but not JSX <img> elements.

Astro image optimization

For relative local images, Astro passes the resulting properties to getImage(). Optimization options such as width, widths, quality, and format control the generated assets:

![A mountain at sunrise](./mountain.jpg)(width: 640, quality: 80, format: avif)

![Responsive mountain](./mountain.jpg)(widths: [320, 640, 960], sizes: "(max-width: 700px) 100vw, 700px")

Attributes such as sizes, loading, decoding, and data attributes appear on the rendered <img>.

Images referenced from public/ with a root-relative path are not optimized.

Defaults

processor: satteri({
  hastPlugins: [
    imgAttr({
      defaults: { loading: "lazy", decoding: "async" },
    }),
  ],
})

Inline attributes override defaults. Properties produced by an earlier plugin are preserved and also take precedence over defaults.

Syntax

The attribute suffix must follow the Markdown image with no intervening whitespace:

![alt](path)(key: value, another: value)

| Value | Example | Result | | --- | --- | --- | | String | loading: lazy | "lazy" | | Number | width: 640 | 640 | | Boolean | defer: true | true | | Quoted string | title: "A wide view" | "A wide view" | | Array | widths: [320, 640] | HAST list value |

Commas inside quotes, arrays, and nested parentheses are preserved. Quote plain string values that contain a top-level comma.

Satteri normalizes HAST list members to strings, so widths: [320, 640] reaches Astro as ["320", "640"]. Astro accepts these numeric list values and generates the requested variants.

How it works

The plugin runs during Satteri's HAST phase, parses a balanced attribute suffix immediately following an <img>, records the resulting properties through the visitor context, and removes the suffix from the rendered output. HAST is used because it preserves list values needed by Astro's widths option.

Direct Satteri usage

pnpm add satteri-imgattr satteri

import { markdownToHtml } from "satteri";
import imgAttr from "satteri-imgattr";

const { html } = markdownToHtml(
  "![alt](photo.jpg)(width: 640)",
  { hastPlugins: [imgAttr()] },
);

Plugin ordering

Satteri runs HAST plugins in array order. Put this plugin before plugins that need to inspect the added image properties.