astro-better-refs 0.1.1 → 0.2.0

package/README.md

@@ -106,6 +106,18 @@ Links are resolved to real URLs at build time. Moving a page or heading only req
 | `failOnBrokenRefs` | `boolean` | `true` | Exit with an error if any `ref:name` link has no matching declaration. |
 | `failOnDuplicateRefs` | `boolean` | `true` | Exit with an error if the same ref name is declared more than once. |
 
+## Sätteri
+
+When `markdown.processor` is a [Sätteri](https://satteri.bruits.org/) processor, the integration adds its Sätteri plugin to it instead of building a unified processor. To cover MDX too, pass a shared `state` to the integration and add the plugin to each processor yourself:
+
+```ts
+import { refs } from 'astro-better-refs/satteri';
+
+const state = { refMap: null, brokenRefs: [], duplicates: [] };
+const processor = satteri({ mdastPlugins: [refs({ state })] });
+// markdown: { processor }, integrations: [mdx({ processor }), astroRef({ collections, state })]
+```
+
 ## Build output
 
 At the end of each build, astro-better-refs reports:

package/core.mjs

@@ -0,0 +1,41 @@
+/**
+ * Ref transforms shared by the unified and Sätteri plugins.
+ */
+
+// Minimal HTML attribute escaping.
+function escAttr(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/**
+ * Split a `## Heading {ref-name}` suffix off a heading's last text value.
+ * Returns { text, refName } or null when there is no suffix.
+ */
+export function splitHeadingRef(value) {
+  const m = value.match(/\s*\{([^}]+)\}\s*$/);
+  if (!m) return null;
+  return { text: value.slice(0, m.index).trimEnd(), refName: m[1].trim() };
+}
+
+/** Invisible anchor inserted before a heading that declares a ref. */
+export function anchorHtml(refName) {
+  return `<span id="${escAttr(refName)}" data-astro-refs="${escAttr(refName)}" aria-hidden="true" class="astro-refs"></span>`;
+}
+
+/**
+ * Resolve a `ref:name` link URL against the ref map. Returns the new URL, or
+ * null for links that don't use the ref: scheme. Unknown refs are recorded in
+ * `state.brokenRefs` and resolve to '#'.
+ */
+export function resolveRefUrl(state, url) {
+  if (typeof url !== 'string' || !url.startsWith('ref:')) return null;
+  const refName = url.slice(4);
+  const entry = state.refMap?.get(refName);
+  if (entry) return entry.url;
+  state.brokenRefs.push(refName);
+  return '#'; // safe fallback; astro-better-refs reports the broken ref
+}

package/index.mjs

@@ -56,6 +56,8 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
+import { anchorHtml, resolveRefUrl, splitHeadingRef } from './core.mjs';
+import { refs as satteriRefs } from './satteri.mjs';
 
 // Walk a directory tree, collecting files whose names end with one of `extensions`.
 async function walkFiles(dir, extensions) {
@@ -180,15 +182,6 @@ async function buildRefMap(collections, rootDir, extensions) {
   return { refMap, duplicates };
 }
 
-// Minimal HTML attribute escaping.
-function escAttr(s) {
-  return String(s)
-    .replace(/&/g, '&')
-    .replace(/"/g, '"')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
-}
-
 // Remark plugin that transforms the Markdown/MDX AST:
 //
 //   [text](ref:name)            →  resolved URL from refMap, or '#' with broken-ref tracking
@@ -202,32 +195,18 @@ function remarkAstroRef({ state }) {
       if (node.type === 'heading') {
         const last = node.children?.[node.children.length - 1];
         if (last?.type === 'text') {
-          const m = last.value.match(/\s*\{([^}]+)\}\s*$/);
-          if (m) {
-            const refName = m[1].trim();
-            last.value = last.value.slice(0, m.index).trimEnd();
-            inserts.push({
-              parent,
-              index,
-              node: {
-                type: 'html',
-                value: `<span id="${escAttr(refName)}" data-astro-refs="${escAttr(refName)}" aria-hidden="true" class="astro-refs"></span>`,
-              },
-            });
+          const split = splitHeadingRef(last.value);
+          if (split) {
+            last.value = split.text;
+            inserts.push({ parent, index, node: { type: 'html', value: anchorHtml(split.refName) } });
           }
         }
       }
 
       // ref: URL scheme on links.
-      if (node.type === 'link' && typeof node.url === 'string' && node.url.startsWith('ref:')) {
-        const refName = node.url.slice(4);
-        const entry = state.refMap?.get(refName);
-        if (entry) {
-          node.url = entry.url;
-        } else {
-          state.brokenRefs.push(refName);
-          node.url = '#'; // safe fallback; astro-better-refs reports the broken ref
-        }
+      if (node.type === 'link') {
+        const url = resolveRefUrl(state, node.url);
+        if (url !== null) node.url = url;
       }
 
       if (Array.isArray(node.children)) {
@@ -304,6 +283,10 @@ export default function astroRef(opts = {}) {
         if (externalState) {
           // caller wires remarkAstroRef manually (e.g. to cover both markdown and mdx processors)
           updateConfig({ vite: { plugins: [vitePlugin] } });
+        } else if (config.markdown?.processor?.name === 'satteri') {
+          // Sätteri processors keep their options mutable for integrations to extend
+          config.markdown.processor.options.mdastPlugins.push(satteriRefs({ state }));
+          updateConfig({ vite: { plugins: [vitePlugin] } });
         } else if (unifiedFn) {
           const existing = config.markdown?.processor;
           const base = (existing && isUnifiedProcessor(existing)) ? existing.options : null;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "astro-better-refs",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Sphinx-style named refs for Astro: declare anchors anywhere, link by name, stay valid when content moves",
   "keywords": [
     "astro",
     "astro-integration",
     "refs",
     "anchors",
-    "cross-references"
+    "cross-references",
+    "satteri"
   ],
   "license": "MIT",
   "author": "Nathan Contino <ncontino@lambdalatitudinarians.org>",
@@ -23,13 +24,36 @@
   "type": "module",
   "exports": {
     ".": "./index.mjs",
+    "./satteri": "./satteri.mjs",
     "./Ref.astro": "./Ref.astro"
   },
   "files": [
     "index.mjs",
+    "core.mjs",
+    "satteri.mjs",
     "Ref.astro"
   ],
   "peerDependencies": {
-    "astro": ">=4.0.0"
+    "astro": ">=4.0.0",
+    "satteri": ">=0.10.0 <0.11.0"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "peerDependenciesMeta": {
+    "satteri": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "hast-util-from-html": "^2.0.3",
+    "rehype-raw": "^7.0.0",
+    "rehype-stringify": "^10.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "satteri": "^0.10.5",
+    "unified": "^11.0.5",
+    "unist-util-remove-position": "^5.0.0"
   }
 }

package/satteri.mjs

@@ -0,0 +1,39 @@
+/**
+ * Sätteri mdast plugin for astro-better-refs. Same transforms as the unified
+ * `remarkAstroRef`:
+ *
+ *   [text](ref:name)            →  resolved URL from refMap, or '#' with broken-ref tracking
+ *   ## Heading {ref-name}       →  strip suffix, insert invisible <span> before heading
+ *
+ * The astroRef integration adds this automatically when `markdown.processor`
+ * is a Sätteri processor. Wire it yourself (with a shared `state`) to cover an
+ * MDX processor as well:
+ *
+ *   import { refs } from 'astro-better-refs/satteri';
+ *   satteri({ mdastPlugins: [refs({ state })] });
+ */
+
+import { anchorHtml, resolveRefUrl, splitHeadingRef } from './core.mjs';
+
+// MDX can't hold html nodes, so parse into JSX there; braces in the HTML stay literal
+const htmlContent = (ctx, html) => ctx.sourceFormat === 'mdx'
+  ? { raw: html, mdxExpressions: false }
+  : { type: 'html', value: html };
+
+export function refs({ state }) {
+  return {
+    name: 'astro-better-refs',
+    heading(node, ctx) {
+      const last = node.children?.[node.children.length - 1];
+      if (last?.type !== 'text') return;
+      const split = splitHeadingRef(last.value);
+      if (!split) return;
+      ctx.setProperty(last, 'value', split.text);
+      ctx.insertBefore(node, htmlContent(ctx, anchorHtml(split.refName)));
+    },
+    link(node, ctx) {
+      const url = resolveRefUrl(state, node.url);
+      if (url !== null) ctx.setProperty(node, 'url', url);
+    },
+  };
+}