Configure markdown processor with native Sätteri plugins

.github/workflows/ci.yml

@@ -41,13 +41,16 @@ jobs:
 
       - run: pnpm build
 
-      # `astro build` exits 0 even when jaamd skips its remark plugins (it only
-      # logs a warning), so a green build is not evidence that the pipeline ran.
-      # This asserts on the rendered HTML, which is what would catch Astro
-      # renaming its default markdown processor out from under us.
+      # `astro build` exits 0 when jaamd skips its plugins (warning only).
+      # Asserts on the rendered HTML; catches a renamed markdown processor.
       - name: Assertions on the built site
         run: pnpm smoke
 
+      # Same assertions on the remark plugins.
+      - run: pnpm build:unified
+      - name: Assertions on the unified build
+        run: pnpm smoke
+
   # `www` pins astro ^7, so the job above never sees a new major. Red here means
   # the next Astro major needs checking, not that main is broken.
   astro-latest:
@@ -71,3 +74,7 @@ jobs:
 
       - name: Assertions against the latest Astro
         run: pnpm smoke
+
+      - run: pnpm build:unified
+      - name: Assertions against the latest Astro, on unified
+        run: pnpm smoke

.github/workflows/publish.yml

@@ -32,6 +32,8 @@ jobs:
       # working: build the showcase and assert on the HTML it produces.
       - run: pnpm build
       - run: pnpm smoke
+      - run: pnpm build:unified
+      - run: pnpm smoke
 
       - name: Publish
         working-directory: packages/jaamd

CONTRIBUTING.md

@@ -5,7 +5,8 @@ pnpm install
 pnpm dev                    # the showcase, on localhost:4321
 pnpm typecheck && pnpm lint
 pnpm test:slug && pnpm test:themes
-pnpm build && pnpm smoke
+pnpm build && pnpm smoke           # on Sätteri, Astro's default
+pnpm build:unified && pnpm smoke   # on unified
 ```
 
 ## Themes

README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  Remark plugins, client-side enhancements and styles as a single <a href="https://astro.build">Astro</a> integration for Markdown content.
+  Markdown plugins, client-side enhancements and styles as a single <a href="https://astro.build">Astro</a> integration for Markdown content.
 </p>
 
 <div align="center">
@@ -42,7 +42,8 @@ Showcase: [jaamd.lancher.dev](https://jaamd.lancher.dev)
 ```bash
 pnpm install
 pnpm dev            # the showcase, on localhost:4321
-pnpm build && pnpm smoke
+pnpm build && pnpm smoke             # on Sätteri, Astro's default
+pnpm build:unified && pnpm smoke     # on unified
 ```
 
 Adding a theme is a directory and a manifest entry: see [CONTRIBUTING.md](/CONTRIBUTING.md#themes).

eslint.config.js

@@ -29,6 +29,7 @@ export default tseslint.config(
       "packages/jaamd/src/paths.ts",
       "packages/jaamd/src/plugins/**/*.ts",
       "packages/jaamd/src/themes/index.ts",
+      "www/astro.config.mjs",
       "tests/**/*.mjs",
       "scripts/**/*.mjs",
     ],

package.json

@@ -8,6 +8,7 @@
   "scripts": {
     "dev": "pnpm --filter www dev",
     "build": "pnpm --filter www build",
+    "build:unified": "JAAMD_PROCESSOR=unified pnpm --filter www build",
     "preview": "pnpm --filter www preview",
     "typecheck": "tsc --noEmit -p packages/jaamd && pnpm --filter www check",
     "lint": "eslint .",

packages/jaamd/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">JAAMD</h1>
 <p align="center">
-  <b>Just Another Astro Markdown</b> — remark plugins, client-side enhancements and styles as a single Astro integration.
+  <b>Just Another Astro Markdown</b> — markdown plugins, client-side enhancements and styles as a single Astro integration.
 </p>
 
 ---
@@ -40,14 +40,25 @@ npx astro add @lancher-dev/jaamd
 
 | Requirement | Detail |
 |---|---|
-| Astro | `>=7.0.0 <8.0.0` |
+| Astro | `^7.3.0` |
+| Node | `>=22.12.0` |
+| Markdown processor | Sätteri (Astro's default) or `unified()` |
 | Toolchain | Must compile TypeScript and `.astro` sources |
 
 JAAMD is published as source, with no compiled `dist/` and no emitted `.d.ts`.
 It works out of the box in any Astro project, but is not consumable from plain
 Node, a CommonJS build, or a TypeScript project using
 `"moduleResolution": "node16"`.
 
+### Upgrading from 0.9
+
+- jaamd no longer switches the markdown processor. With no configuration you
+  are on Sätteri.
+- Set `markdown.processor: unified()` to stay on unified.
+- `markdown.remarkPlugins` and `markdown.rehypePlugins` still work: Astro moves
+  to unified, jaamd adds its remark plugins.
+- Astro `^7.3.0` is required.
+
 ## Setup
 
 Add the integration to your Astro config:
@@ -74,8 +85,12 @@ import MarkdownContent from "@lancher-dev/jaamd/components";
 </MarkdownContent>
 ```
 
-The integration registers all remark plugins and injects the stylesheet
-automatically. No other configuration is required.
+The integration registers its plugins on the configured markdown processor and
+injects the stylesheet automatically. No other configuration is required.
+
+The processor is extended, never replaced: Sätteri gets mdast plugins and the
+directive syntax, `unified()` gets the remark plugins. Any other processor is
+left alone, with a warning.
 
 > [!IMPORTANT]
 > `<MarkdownContent>` loads the stylesheets for you. If you render markdown
@@ -99,7 +114,7 @@ jaamd({
     codeTabs:  true,            // :::code-tabs directive blocks
     toc:       true,            // :::toc directive blocks
     alerts:    true,            // > [!NOTE] / [!WARNING] blockquote alerts
-    directive: true,            // remark-directive (prerequisite for codeTabs and toc)
+    directive: true,            // `:::` syntax (prerequisite for codeTabs and toc)
   },
 })
 ```
@@ -205,7 +220,7 @@ never went through Astro's pipeline (`set:html`, HTML from a CMS).
 With a sticky header, raise `--jaamd-scroll-margin-top` (default `80px`).
 
 > [!NOTE]
-> `:::toc` needs `remark-directive`, on by default. With `plugins: { toc: false }`
+> `:::toc` needs the directive syntax, on by default. With `plugins: { toc: false }`
 > the block degrades to a plain `<div>`: list and links intact, unstyled.
 
 ### Spoilers
@@ -457,19 +472,43 @@ Add an inline script in `<head>` to prevent a flash of the wrong theme:
 
 ## Manual / Advanced Usage
 
-To bypass the integration, register the plugins yourself. Astro's default
-markdown processor does not run `markdown.remarkPlugins`, so pass the `unified`
-processor from `@astrojs/markdown-remark` explicitly:
+To bypass the integration, register the plugins yourself on the processor you
+use. On Sätteri, Astro's default:
+
+```ts
+// astro.config.mjs
+import { satteri } from "@astrojs/markdown-satteri";
+import {
+  satteriAlert,
+  satteriCodeTabs,
+  satteriToc,
+  satteriDirectiveFallback,
+} from "@lancher-dev/jaamd";
+
+export default defineConfig({
+  markdown: {
+    processor: satteri({
+      features: { directive: true },
+      mdastPlugins: [satteriAlert, satteriCodeTabs, satteriToc, satteriDirectiveFallback],
+    }),
+  },
+});
+```
+
+`satteriDirectiveFallback` keeps directives no plugin handles, which Sätteri
+drops: blocks as a plain `<div>`, an inline `:name` as typed. Put it last.
+
+On unified:
 
 ```ts
 // astro.config.mjs
 import { unified } from "@astrojs/markdown-remark";
-import { remarkCodeTabs, remarkAlert, remarkDirective } from "@lancher-dev/jaamd";
+import { remarkAlert, remarkCodeTabs, remarkDirective, remarkToc } from "@lancher-dev/jaamd";
 
 export default defineConfig({
   markdown: {
     processor: unified({
-      remarkPlugins: [remarkAlert, remarkDirective, remarkCodeTabs],
+      remarkPlugins: [remarkAlert, remarkDirective, remarkCodeTabs, remarkToc],
     }),
   },
 });