blume 0.0.0 → 0.1.1

package/src/markdown/directives.ts

@@ -0,0 +1,83 @@
+import { jsxAttribute, jsxFlowElement } from "./mdast.ts";
+import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
+
+interface DirectiveNode extends MdastNode {
+  attributes?: Record<string, string | null | undefined> | null;
+  children: MdastNode[];
+  name: string;
+}
+
+/** Directive names that map directly onto a Callout type. */
+const CALLOUT_TYPES = new Set([
+  "danger",
+  "info",
+  "note",
+  "success",
+  "tip",
+  "warning",
+]);
+
+/** Friendly aliases for the canonical Callout types. */
+const ALIASES: Record<string, string> = {
+  caution: "warning",
+  error: "danger",
+  important: "note",
+  warn: "warning",
+};
+
+/** Resolve a directive name to a Callout type, or `null` if it is not one. */
+export const calloutTypeFor = (name: string): string | null => {
+  const lower = name.toLowerCase();
+  if (CALLOUT_TYPES.has(lower)) {
+    return lower;
+  }
+  return ALIASES[lower] ?? null;
+};
+
+interface TextNode extends MdastNode {
+  value?: string;
+}
+
+/** Concatenate the plain text of a node's immediate phrasing children. */
+const textOf = (node: MdastNode): string =>
+  ((node.children as TextNode[] | undefined) ?? [])
+    .map((child) => child.value ?? "")
+    .join("");
+
+/**
+ * Satteri MDAST plugin mapping container directives (`:::note`, `:::warning`,
+ * `:::tip`, …) onto Blume's `<Callout>` component. The title comes from a
+ * `[label]` or a `{title="…"}` attribute; the body becomes the callout content.
+ * Directive names that are not callouts are left untouched.
+ */
+export const directiveToCalloutPlugin = () => ({
+  containerDirective(node: DirectiveNode, ctx: MdastVisitorContext) {
+    const type = calloutTypeFor(node.name);
+    if (type === null) {
+      return;
+    }
+
+    const children = [...node.children];
+    let title = node.attributes?.title ?? undefined;
+
+    // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.
+    const labelIndex = children.findIndex(
+      (child) =>
+        child.type === "paragraph" &&
+        (child.data as { directiveLabel?: boolean } | undefined)?.directiveLabel
+    );
+    if (labelIndex !== -1) {
+      const [label] = children.splice(labelIndex, 1);
+      if (label) {
+        title ??= textOf(label) || undefined;
+      }
+    }
+
+    const attributes = [jsxAttribute("type", type)];
+    if (title) {
+      attributes.push(jsxAttribute("title", title));
+    }
+    ctx.replaceNode(node, jsxFlowElement("Callout", attributes, children));
+  },
+  name: "blume-directive-callout",
+});

package/src/markdown/heading-anchors.ts

@@ -0,0 +1,137 @@
+/**
+ * Turn every section heading into its own permalink. A Satteri hast plugin runs
+ * after Markdown is turned into hast and wraps each `<h2>`–`<h6>`'s content in an
+ * `<a href="#slug">`, so a reader can click the heading to copy, bookmark, or
+ * share a link straight to that section. `<h1>` (the page title) is slugged for
+ * parity but left unwrapped.
+ *
+ * Satteri's own `heading-ids` plugin (which assigns the `id` used by the table
+ * of contents) runs *after* every user hast plugin, and it reuses an `id` that
+ * is already present rather than re-slugging. So this plugin is the authoritative
+ * id setter: it slugs each heading with the same algorithm (a per-document
+ * `github-slugger`, the library Satteri and rehype-slug both use) and writes the
+ * `id`, which `heading-ids` then adopts — keeping the in-page anchor, the
+ * heading's `id`, and the TOC entry in lockstep. To match Satteri's duplicate
+ * disambiguation (`setup`, `setup-1`, …) exactly, it advances the slugger over
+ * `<h1>`–`<h6>` in document order even though only `<h2>`–`<h6>` get wrapped.
+ */
+
+import { satteriCollectHastText } from "@astrojs/markdown-satteri";
+import GithubSlugger from "github-slugger";
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  name?: string;
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  type: string;
+  value?: string;
+}
+
+/** The slice of Satteri's hast visitor context this plugin reads. */
+interface HastContext {
+  data?: { astro?: { frontmatter?: Record<string, unknown> } };
+  setProperty: (node: HastNode, key: string, value: unknown) => void;
+  textContent: (node: HastNode) => string;
+}
+
+/** A Satteri hast plugin, typed structurally to avoid a Satteri dep. */
+export interface HeadingAnchorPlugin {
+  name: string;
+  element: {
+    filter: string[];
+    visit: (node: HastNode, ctx: HastContext) => HastNode | undefined;
+  };
+}
+
+/** Headings slugged for id parity with Satteri; only a subset gets wrapped. */
+const HEADINGS = ["h1", "h2", "h3", "h4", "h5", "h6"];
+const WRAPPED = new Set(["h2", "h3", "h4", "h5", "h6"]);
+
+/** True if the subtree already contains an `<a>`, so wrapping would nest links. */
+const containsAnchor = (node: HastNode): boolean => {
+  for (const child of node.children ?? []) {
+    if ((child.tagName ?? child.name) === "a" || containsAnchor(child)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+// One slugger per document render. The plugin instance is shared across every
+// page, but slug disambiguation must reset per document; the render-scoped
+// `astro` data object is a stable, unique key for one render (entries are
+// dropped once the render is collected, so this never leaks).
+const FALLBACK_SCOPE: object = {};
+const sluggers = new WeakMap<object, GithubSlugger>();
+
+const sluggerFor = (ctx: HastContext): GithubSlugger => {
+  const scope = ctx.data?.astro ?? ctx.data ?? FALLBACK_SCOPE;
+  const existing = sluggers.get(scope);
+  if (existing) {
+    return existing;
+  }
+  const slugger = new GithubSlugger();
+  sluggers.set(scope, slugger);
+  return slugger;
+};
+
+/** The slug for a heading, mirroring Satteri's `heading-ids` exactly. */
+const slugFor = (
+  node: HastNode,
+  ctx: HastContext,
+  slugger: GithubSlugger
+): string => {
+  const rawText = ctx.textContent(node);
+  // `frontmatter`-interpolated MDX headings (`## {frontmatter.title}`) need the
+  // resolved value; the helper is the same one `heading-ids` defers to.
+  const text = rawText.includes("frontmatter")
+    ? satteriCollectHastText(
+        node as Parameters<typeof satteriCollectHastText>[0],
+        ctx.data?.astro?.frontmatter ?? {}
+      )
+    : rawText;
+  const existingId = node.properties?.id;
+  return typeof existingId === "string" ? existingId : slugger.slug(text);
+};
+
+/** Build the plugin. Wraps `<h2>`–`<h6>` in self-linking anchors. */
+export const headingAnchorPlugin = (): HeadingAnchorPlugin => ({
+  element: {
+    filter: HEADINGS,
+    visit(node, ctx) {
+      const slug = slugFor(node, ctx, sluggerFor(ctx));
+      const wrap = node.tagName
+        ? WRAPPED.has(node.tagName) && slug !== "" && !containsAnchor(node)
+        : false;
+      if (!wrap) {
+        // Unwrapped headings (h1, an empty slug, or one that already links) still
+        // need the id so `heading-ids` adopts it instead of re-slugging.
+        if (typeof node.properties?.id !== "string") {
+          ctx.setProperty(node, "id", slug);
+        }
+        return;
+      }
+      // Replacing the heading re-emits its original children as refs inside the
+      // new anchor (Satteri passes reused nodes through untouched).
+      return {
+        children: [
+          {
+            children: node.children ?? [],
+            properties: {
+              className: ["blume-heading-anchor"],
+              href: `#${slug}`,
+            },
+            tagName: "a",
+            type: "element",
+          },
+        ],
+        properties: { ...node.properties, id: slug },
+        tagName: node.tagName,
+        type: "element",
+      };
+    },
+  },
+  name: "blume:heading-anchors",
+});

package/src/markdown/index.ts

@@ -0,0 +1,228 @@
+import { satteri } from "@astrojs/markdown-satteri";
+import {
+  transformerMetaHighlight,
+  transformerNotationDiff,
+  transformerNotationFocus,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight,
+} from "@shikijs/transformers";
+import { codeToHtml } from "shiki";
+
+import { codeTitleTransformer } from "./code-title.ts";
+import { directiveToCalloutPlugin } from "./directives.ts";
+import { headingAnchorPlugin } from "./heading-anchors.ts";
+import { inlineCodeHighlightPlugin } from "./inline-code.ts";
+import { languageIconTransformer } from "./language-icon.ts";
+import { mathPlugin } from "./math.ts";
+import { mermaidPlugin } from "./mermaid.ts";
+import { packageInstallPlugin } from "./package-install.ts";
+
+/** A Shiki transformer, derived from the upstream factories' return type. */
+type ShikiTransformer = ReturnType<typeof transformerNotationDiff>;
+
+export {
+  PACKAGE_MANAGERS,
+  type PackageManager,
+  toPackageCommands,
+} from "./package-commands.ts";
+export {
+  type CodeTitleTransformer,
+  codeTitleTransformer,
+} from "./code-title.ts";
+export { calloutTypeFor } from "./directives.ts";
+export { headingAnchorPlugin } from "./heading-anchors.ts";
+export { mermaidPlugin } from "./mermaid.ts";
+export { packageInstallPlugin } from "./package-install.ts";
+
+/** Element type of Satteri's `mdastPlugins`, sourced from the (alpha) core. */
+type MdastPlugin = NonNullable<
+  NonNullable<Parameters<typeof satteri>[0]>["mdastPlugins"]
+>[number];
+
+/** Element type of Satteri's `hastPlugins`. */
+type HastPlugin = NonNullable<
+  NonNullable<Parameters<typeof satteri>[0]>["hastPlugins"]
+>[number];
+
+/**
+ * Hast plugins enabled by config. Inline `` `code`{:lang} `` highlighting is
+ * opt-in; self-linking heading anchors (`<h2>`–`<h6>` wrapped in an `<a>` to
+ * their own id) are on unless `markdown.headingAnchors` is `false`. Inline code
+ * runs first so the anchor wrap re-refs already-highlighted code.
+ */
+const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
+  const plugins: HastPlugin[] = [];
+  if (options.inline) {
+    plugins.push(inlineCodeHighlightPlugin() as unknown as HastPlugin);
+  }
+  if (options.headingAnchors !== false) {
+    plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
+  }
+  return plugins;
+};
+
+/**
+ * Shiki transformers enabled by default for every code block. The four upstream
+ * notation transformers read GitHub-style comments and strip them from the
+ * output: `// [!code highlight]`, `// [!code ++]` / `// [!code --]`,
+ * `// [!code word:x]`, and `// [!code focus]`. The v3 match algorithm scopes a
+ * notation to the line it sits on (or the next, for a trailing comment).
+ * `transformerMetaHighlight` adds numeric range highlighting from the fence meta
+ * (` ```ts {1,3-5} `), reusing the same `highlighted` class. Blume's own
+ * {@link languageIconTransformer} prepends a brand icon, and
+ * {@link codeTitleTransformer} runs last to promote fence-meta (title / line
+ * numbers) to `<pre>` attributes. The theme styles the classes these emit
+ * (`highlighted`, `diff add/remove`, `highlighted-word`, `focused`,
+ * `blume-lang-icon`).
+ */
+export interface BlumeShikiOptions {
+  /** Prepend a brand language icon to the header (`markdown.code.icons`). */
+  icons?: boolean;
+}
+
+export const blumeShikiTransformers = (
+  options: BlumeShikiOptions = {}
+): ShikiTransformer[] => {
+  const transformers: ShikiTransformer[] = [
+    transformerNotationHighlight({ matchAlgorithm: "v3" }),
+    transformerNotationDiff({ matchAlgorithm: "v3" }),
+    transformerNotationWordHighlight({ matchAlgorithm: "v3" }),
+    transformerNotationFocus({ matchAlgorithm: "v3" }),
+    transformerMetaHighlight(),
+  ];
+  if (options.icons !== false) {
+    transformers.push(languageIconTransformer() as unknown as ShikiTransformer);
+  }
+  // The fence-meta reader (title / line numbers) always runs last.
+  transformers.push(codeTitleTransformer() as unknown as ShikiTransformer);
+  return transformers;
+};
+
+/**
+ * The light/dark Shiki themes Blume highlights with. Kept in lockstep with the
+ * generated Astro config's `shikiConfig.themes` so code highlighted outside the
+ * Markdown pipeline (via {@link highlightCode}) matches fenced code exactly.
+ */
+const CODE_THEMES = { dark: "github-dark", light: "github-light" } as const;
+
+const escapeHtml = (value: string): string =>
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+/**
+ * Tag the highlighted `<pre>` with `astro-code` (plus any extra classes) so the
+ * theme's code-block styles apply — `codeToHtml`'s bare output is `pre.shiki`,
+ * which the theme doesn't style.
+ */
+const astroCodeClassTransformer = (extra?: string): ShikiTransformer =>
+  ({
+    name: "blume:astro-code-class",
+    pre(node: { properties: Record<string, unknown> }) {
+      const existing =
+        typeof node.properties.class === "string" ? node.properties.class : "";
+      node.properties.class = `astro-code ${extra ?? ""} ${existing}`
+        .replaceAll(/\s+/gu, " ")
+        .trim();
+    },
+  }) as unknown as ShikiTransformer;
+
+export interface HighlightCodeOptions extends BlumeShikiOptions {
+  /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
+  className?: string;
+}
+
+/**
+ * Highlight a code string with the same Shiki themes and transformers as Blume's
+ * Markdown code fences, returning ready-to-render HTML. Use it to show themed
+ * code *outside* the Markdown pipeline (custom pages, components): the output
+ * carries the `astro-code` class and dual (light/dark) color variables, so the
+ * theme styles it — including the light/dark swap — with no extra CSS. The
+ * theme's code-block rules are scoped to `.prose`, so render the result inside a
+ * `.prose` container (the shipped `<CodeBlock>` does this). An unknown language
+ * falls back to an escaped plain block.
+ */
+export const highlightCode = async (
+  code: string,
+  lang: string,
+  options: HighlightCodeOptions = {}
+): Promise<string> => {
+  try {
+    return await codeToHtml(code, {
+      defaultColor: false,
+      lang,
+      themes: CODE_THEMES,
+      transformers: [
+        ...blumeShikiTransformers({ icons: options.icons }),
+        astroCodeClassTransformer(options.className),
+      ],
+    });
+  } catch {
+    const className = `astro-code ${options.className ?? ""}`
+      .replaceAll(/\s+/gu, " ")
+      .trim();
+    return `<pre class="${className}"><code>${escapeHtml(code)}</code></pre>`;
+  }
+};
+
+/**
+ * Sätteri Markdown features Blume enables beyond Astro's defaults. GFM,
+ * frontmatter, and smart punctuation are already on; this adds superscript
+ * (`^text^`) and subscript (`~text~`), which render to native `<sup>`/`<sub>`.
+ */
+const FEATURES = { subscript: true, superscript: true };
+
+/** Options shared by both processors. */
+export interface BlumeMarkdownOptions {
+  /**
+   * Wrap `<h2>`–`<h6>` in self-linking anchors (`markdown.headingAnchors`).
+   * On unless explicitly `false`.
+   */
+  headingAnchors?: boolean;
+  /** Highlight inline `` `code`{:lang} `` snippets (`markdown.code.inline`). */
+  inline?: boolean;
+}
+
+/** Sätteri processor for plain `.md`, with Blume's curated feature set. */
+export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
+  satteri({
+    features: { ...FEATURES },
+    hastPlugins: blumeHastPlugins(options),
+  });
+
+export interface BlumeMdxOptions extends BlumeMarkdownOptions {
+  /** Enable KaTeX math parsing and rendering. */
+  math?: boolean;
+}
+
+/**
+ * Sätteri MDX processor: Blume's feature set plus the MDAST plugins that target
+ * components — `package-install` → package-manager tabs, `:::note` →
+ * `<Callout>`, and ` ```mermaid ` → a `<blume-mermaid>` element. Used as the
+ * `processor` for `@astrojs/mdx` so these apply to
+ * `.mdx` only (plain `.md` uses {@link blumeMarkdownProcessor}). Math is opt-in
+ * via config since `$` is common in prose and code.
+ *
+ * The plugins are modeled with minimal structural types; bridge them to
+ * Satteri's full `MdastPlugin` type at this single boundary.
+ */
+export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) => {
+  const plugins: unknown[] = [
+    packageInstallPlugin(),
+    directiveToCalloutPlugin(),
+    mermaidPlugin(),
+  ];
+  if (options.math) {
+    plugins.push(mathPlugin());
+  }
+  return satteri({
+    features: {
+      ...FEATURES,
+      directive: true,
+      ...(options.math ? { math: true } : {}),
+    },
+    hastPlugins: blumeHastPlugins(options),
+    mdastPlugins: plugins as unknown as MdastPlugin[],
+  });
+};

package/src/markdown/inline-code.ts

@@ -0,0 +1,108 @@
+/**
+ * Inline syntax highlighting for `` `code{:lang}` ``. A Satteri hast plugin runs
+ * after Markdown is turned into hast and looks at each inline `<code>` for a
+ * trailing `{:lang}` marker. The marker sits *inside* the backticks (Shiki's
+ * "tailing-curly-colon" convention) so it survives MDX, where a `{…}` after a
+ * code span would be parsed as a JSX expression. When found, it strips the
+ * marker and replaces the code's text with Shiki tokens (dual github-light/dark
+ * via CSS variables, like fenced blocks).
+ *
+ * Shiki is imported lazily, so it loads only on pages that actually use inline
+ * highlighting — and never when `markdown.code.inline` is off (the plugin is not
+ * added to the pipeline at all).
+ */
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  type: string;
+  value?: string;
+}
+
+/** The slice of Satteri's hast visitor context this plugin reads. */
+interface HastContext {
+  parent: (node: HastNode) => { tagName?: string } | undefined;
+  textContent: (node: HastNode) => string;
+}
+
+/** A Satteri hast plugin, typed structurally to avoid a Satteri dep. */
+export interface InlineCodePlugin {
+  name: string;
+  element: {
+    filter: string[];
+    visit: (node: HastNode, ctx: HastContext) => Promise<HastNode | undefined>;
+  };
+}
+
+/** Parsed `{:lang}` marker and the code with it removed. */
+export interface InlineLang {
+  code: string;
+  lang: string;
+}
+
+const INLINE_LANG = /\{:(?<lang>[\w+-]+)\}$/u;
+
+/** Parse a trailing `{:lang}` marker from an inline `<code>`'s own text. */
+export const parseInlineLang = (text: string): InlineLang | null => {
+  const match = text.match(INLINE_LANG);
+  if (!match?.groups?.lang || match.index === undefined) {
+    return null;
+  }
+  const code = text.slice(0, match.index);
+  return code ? { code, lang: match.groups.lang } : null;
+};
+
+/** Loosely-typed Shiki entry: just the inline-highlight call this plugin makes. */
+type InlineHighlighter = (
+  code: string,
+  options: {
+    defaultColor: false;
+    lang: string;
+    structure: "inline";
+    themes: { dark: string; light: string };
+  }
+) => Promise<{ children: HastNode[] }>;
+
+// `import()` caches the module, so this dedupes Shiki across calls on its own.
+const loadHighlighter = async (): Promise<InlineHighlighter> => {
+  const mod = await import("shiki");
+  return mod.codeToHast as unknown as InlineHighlighter;
+};
+
+/** Build the plugin. Highlights inline `` `code{:lang}` `` snippets. */
+export const inlineCodeHighlightPlugin = (): InlineCodePlugin => ({
+  element: {
+    filter: ["code"],
+    async visit(node, ctx) {
+      // Only inline code: a <code> inside <pre> is a fenced block — skip it.
+      if (ctx.parent(node)?.tagName === "pre") {
+        return;
+      }
+      const parsed = parseInlineLang(ctx.textContent(node));
+      if (!parsed) {
+        return;
+      }
+      try {
+        const codeToHast = await loadHighlighter();
+        const root = await codeToHast(parsed.code, {
+          defaultColor: false,
+          lang: parsed.lang,
+          structure: "inline",
+          themes: { dark: "github-dark", light: "github-light" },
+        });
+        return {
+          children: root.children,
+          properties: { className: ["blume-inline-code"] },
+          tagName: "code",
+          type: "element",
+        };
+      } catch {
+        // Unknown language or load failure: leave the code unhighlighted
+        // (falling through returns undefined, so the node is left as-is).
+      }
+    },
+  },
+  name: "blume:inline-code",
+});