@hutusi/amytis 1.14.0 → 1.16.0

package/src/lib/shiki-rst.ts

@@ -0,0 +1,185 @@
+import { unified } from 'unified';
+import rehypeParse from 'rehype-parse';
+import { visit } from 'unist-util-visit';
+import { toHtml } from 'hast-util-to-html';
+import type { Element, Root, RootContent } from 'hast';
+import { expandLineRanges, highlightToHast } from './shiki';
+import { resolveCodeGroupIcon } from './code-group-icons';
+
+interface AmytisCodeMarker {
+  element: Element;
+  code: string;
+  language: string;
+  highlightLines: number[];
+  showLineNumbers: boolean;
+  title: string | undefined;
+}
+
+function getAttr(node: Element, name: string): string | undefined {
+  const value = node.properties?.[name];
+  if (value == null) return undefined;
+  if (Array.isArray(value)) return value.join(' ');
+  return String(value);
+}
+
+function isAmytisCodeMarker(node: Element): boolean {
+  return node.tagName === 'pre' && node.properties != null && 'dataAmytisCode' in node.properties;
+}
+
+function isAmytisCodeGroupMarker(node: Element): boolean {
+  return node.tagName === 'div' && node.properties != null && 'dataAmytisCodeGroup' in node.properties;
+}
+
+function extractCode(element: Element): string {
+  // The marker shape is <pre data-amytis-code><code>...</code></pre>
+  const codeChild = element.children.find(
+    (child): child is Element => child.type === 'element' && child.tagName === 'code',
+  );
+  if (!codeChild) return '';
+  let buffer = '';
+  for (const child of codeChild.children) {
+    if (child.type === 'text') buffer += child.value;
+  }
+  return buffer;
+}
+
+function readMarker(element: Element): AmytisCodeMarker {
+  const code = extractCode(element);
+  const language = getAttr(element, 'dataLanguage') ?? '';
+  const highlightLinesAttr = getAttr(element, 'dataHighlightLines');
+  const highlightLines = highlightLinesAttr ? expandLineRanges(highlightLinesAttr) : [];
+  const showLineNumbers = (getAttr(element, 'dataLineNumbers') ?? '').toLowerCase() === 'true';
+  const titleAttr = getAttr(element, 'dataTitle');
+  const title = titleAttr && titleAttr.trim().length > 0 ? titleAttr : undefined;
+
+  return { element, code, language, highlightLines, showLineNumbers, title };
+}
+
+/**
+ * Walks rendered rST HTML for opaque <pre data-amytis-code> markers (emitted by
+ * scripts/render-rst.py for every literal_block) and replaces each with Shiki's
+ * highlighted output. Same highlighter singleton + transformers as the MDX/Markdown
+ * path, so rST and Markdown code blocks render identically.
+ */
+export async function applyShikiToRstHtml(html: string): Promise<string> {
+  const tree = unified()
+    .use(rehypeParse, { fragment: true })
+    .parse(html) as Root;
+
+  const markers: AmytisCodeMarker[] = [];
+  visit(tree, 'element', (node: Element) => {
+    if (isAmytisCodeMarker(node)) {
+      markers.push(readMarker(node));
+    }
+  });
+
+  if (markers.length === 0) {
+    return html;
+  }
+
+  const highlighted = new Map<Element, RootContent[]>();
+  for (const marker of markers) {
+    const hast = await highlightToHast(marker.code, marker.language, {
+      showLineNumbers: marker.showLineNumbers,
+      highlightLines: marker.highlightLines,
+      title: marker.title,
+    });
+    highlighted.set(marker.element, hast.children as RootContent[]);
+  }
+
+  visit(tree, 'element', (node: Element) => {
+    if (!isAmytisCodeMarker(node)) return;
+    const replacement = highlighted.get(node);
+    if (!replacement || replacement.length === 0) return;
+    // Promote the highlighted <pre> in place by mutating the marker into a wrapper.
+    // We replace the marker element's tagName/properties/children with the first
+    // (and only) <pre> from Shiki's output. rehype-parse strips DOCTYPEs etc.
+    const first = replacement[0];
+    if (first.type !== 'element') return;
+    node.tagName = first.tagName;
+    node.properties = first.properties ?? {};
+    node.children = first.children;
+  });
+
+  // Second pass: rewrite <div data-amytis-code-group> markers into the same
+  // radio+label tab structure that CodeGroup.tsx emits, so the existing
+  // .code-group CSS rules style both pipelines identically.
+  visit(tree, 'element', (node: Element) => {
+    if (!isAmytisCodeGroupMarker(node)) return;
+
+    const labelsAttr = getAttr(node, 'dataLabels') ?? '[]';
+    const groupId = getAttr(node, 'dataGroupId') ?? `cg-${Math.random().toString(36).slice(2, 8)}`;
+    let labels: string[];
+    try {
+      const parsed = JSON.parse(labelsAttr);
+      labels = Array.isArray(parsed) ? parsed.map(String) : [];
+    } catch {
+      labels = [];
+    }
+
+    // The marker's children are the already-highlighted <pre class="shiki"> blocks
+    // (from the first pass) — or fallback bare nodes if something went sideways.
+    const panels = node.children.filter(
+      (child): child is Element => child.type === 'element',
+    );
+    const tabs = labels.length > 0 ? labels : panels.map((_, i) => `Tab ${i + 1}`);
+
+    const radioInputs: Element[] = tabs.map((_, i) => ({
+      type: 'element',
+      tagName: 'input',
+      properties: {
+        type: 'radio',
+        name: `cg-${groupId}`,
+        id: `cg-${groupId}-${i}`,
+        'data-idx': String(i),
+        ...(i === 0 ? { checked: true } : {}),
+        'aria-controls': `cg-${groupId}-panel-${i}`,
+        tabIndex: i === 0 ? 0 : -1,
+      },
+      children: [],
+    }));
+
+    const tabLabels: Element[] = tabs.map((label, i) => {
+      const icon = resolveCodeGroupIcon(label);
+      return {
+        type: 'element' as const,
+        tagName: 'label',
+        properties: {
+          htmlFor: `cg-${groupId}-${i}`,
+          className: ['cg-tab'],
+          role: 'tab',
+          ...(icon ? { 'data-cg-icon': icon } : {}),
+        },
+        children: [{ type: 'text' as const, value: label }],
+      };
+    });
+
+    const tablist: Element = {
+      type: 'element',
+      tagName: 'div',
+      properties: { className: ['cg-tablist'], role: 'tablist' },
+      children: tabLabels,
+    };
+
+    const panelDivs: Element[] = panels.map((panel, i) => ({
+      type: 'element',
+      tagName: 'div',
+      properties: {
+        className: ['cg-panel'],
+        'data-panel': String(i),
+        role: 'tabpanel',
+        id: `cg-${groupId}-panel-${i}`,
+      },
+      children: [panel],
+    }));
+
+    node.tagName = 'div';
+    node.properties = {
+      className: ['code-group', 'my-6'],
+      'data-group-id': groupId,
+    };
+    node.children = [...radioInputs, tablist, ...panelDivs];
+  });
+
+  return toHtml(tree);
+}

package/src/lib/shiki.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, mock, spyOn, test } from 'bun:test';
+import {
+  getLanguageDisplayName,
+  highlightToHast,
+  parseFenceMeta,
+  resetUnknownLangWarningsForTests,
+} from './shiki';
+
+describe('parseFenceMeta', () => {
+  test('returns empty object for empty input', () => {
+    expect(parseFenceMeta(undefined)).toEqual({});
+    expect(parseFenceMeta(null)).toEqual({});
+    expect(parseFenceMeta('')).toEqual({});
+  });
+
+  test('extracts title from title="..."', () => {
+    expect(parseFenceMeta('title="src/app.ts"').title).toBe('src/app.ts');
+  });
+
+  test('flags linenos', () => {
+    expect(parseFenceMeta('linenos').showLineNumbers).toBe(true);
+  });
+
+  test('expands {1,3-5} highlight ranges', () => {
+    expect(parseFenceMeta('{1,3-5}').highlightLines).toEqual([1, 3, 4, 5]);
+  });
+
+  test('extracts [label] at the start as tabLabel', () => {
+    expect(parseFenceMeta('[npm]').tabLabel).toBe('npm');
+    expect(parseFenceMeta(' [yarn] ').tabLabel).toBe('yarn');
+  });
+
+  test('does not confuse [label] with the {1,3-5} highlight syntax', () => {
+    // Square brackets and curly braces are distinct — different meta features.
+    const result = parseFenceMeta('[npm] {1,3-5}');
+    expect(result.tabLabel).toBe('npm');
+    expect(result.highlightLines).toEqual([1, 3, 4, 5]);
+  });
+
+  test('combines all meta fields in one fence', () => {
+    const result = parseFenceMeta('[npm] title="install.sh" linenos {1,3-5}');
+    expect(result.tabLabel).toBe('npm');
+    expect(result.title).toBe('install.sh');
+    expect(result.showLineNumbers).toBe(true);
+    expect(result.highlightLines).toEqual([1, 3, 4, 5]);
+  });
+
+  test('ignores [label] that is not at the start of the meta', () => {
+    // The convention is [label] FIRST. A bracket-token deeper into the meta is
+    // not interpreted as a label — keeps the grammar unambiguous.
+    expect(parseFenceMeta('linenos [late]').tabLabel).toBeUndefined();
+  });
+
+  test('whitespace-only [   ] does not leak an empty-string label', () => {
+    // `[   ]` would otherwise produce an empty string, which bypasses downstream
+    // `?? language` fallbacks (empty string isn't nullish). Result: blank tabs.
+    expect(parseFenceMeta('[   ]').tabLabel).toBeUndefined();
+    expect(parseFenceMeta('[]').tabLabel).toBeUndefined();
+  });
+});
+
+describe('getLanguageDisplayName', () => {
+  test('returns the proper-case brand form for a canonical language', () => {
+    expect(getLanguageDisplayName('typescript')).toBe('TypeScript');
+    expect(getLanguageDisplayName('python')).toBe('Python');
+    expect(getLanguageDisplayName('ocaml')).toBe('OCaml');
+  });
+
+  test('resolves aliases to the canonical display name', () => {
+    expect(getLanguageDisplayName('ts')).toBe('TypeScript');
+    expect(getLanguageDisplayName('js')).toBe('JavaScript');
+    expect(getLanguageDisplayName('py')).toBe('Python');
+  });
+
+  test('handles alias tokens with special characters', () => {
+    // `c++` is a Shiki alias that resolves to `cpp` → `C++` display.
+    expect(getLanguageDisplayName('c++')).toBe('C++');
+  });
+
+  test('falls back to the raw input for unrecognized languages', () => {
+    // Defensive — highlightToHast throws on unknown langs, so this branch is
+    // only reachable for callers that opt to render a label without highlighting.
+    expect(getLanguageDisplayName('totally-fake')).toBe('totally-fake');
+  });
+
+  test('handles plaintext aliases', () => {
+    expect(getLanguageDisplayName('plaintext')).toBe('Plain text');
+    expect(getLanguageDisplayName('text')).toBe('Plain text');
+    expect(getLanguageDisplayName('txt')).toBe('Plain text');
+  });
+
+  test('resolves previously-unregistered Shiki langs (regression: production build)', () => {
+    // Before the lazy-load refactor, `make` was rejected at build time because it
+    // wasn't in a hand-maintained SHIKI_LANGS list. Now resolved via Shiki's bundle.
+    expect(getLanguageDisplayName('make')).toBe('Makefile');
+    expect(getLanguageDisplayName('makefile')).toBe('Makefile');
+    expect(getLanguageDisplayName('dockerfile')).toBe('Dockerfile');
+    expect(getLanguageDisplayName('toml')).toBe('TOML');
+    expect(getLanguageDisplayName('kotlin')).toBe('Kotlin');
+  });
+
+  test('resolves community aliases Shiki does not ship natively (regression: golang)', () => {
+    // Shiki's bundledLanguagesInfo for `go` does not list `golang` as an alias,
+    // and similarly for several other community-written names. The
+    // COMMUNITY_ALIASES overlay in shiki.ts adds them.
+    expect(getLanguageDisplayName('golang')).toBe('Go');
+    expect(getLanguageDisplayName('node')).toBe('JavaScript');
+    expect(getLanguageDisplayName('nodejs')).toBe('JavaScript');
+    expect(getLanguageDisplayName('obj-c')).toBe('Objective-C');
+    expect(getLanguageDisplayName('gnumakefile')).toBe('Makefile');
+    expect(getLanguageDisplayName('bsdmakefile')).toBe('Makefile');
+  });
+});
+
+describe('highlightToHast strict-build behavior', () => {
+  test('lazy-loads any language in Shiki bundle (previously-unregistered: make)', async () => {
+    // Regression: the production build broke when a real post used ```make. Strict-build
+    // is supposed to fail typos, not legitimate bundled languages — this test locks in
+    // that any bundled lang works without prior registration.
+    const hast = await highlightToHast('all:\n\t@echo hi\n', 'make');
+    expect(hast.type).toBe('root');
+    // The highlighted output should contain at least one element.
+    expect(hast.children.length).toBeGreaterThan(0);
+  });
+
+  test('renders unknown languages as plaintext + emits a deduped warn', async () => {
+    // Warn-and-degrade: a typo'd or otherwise unknown fence language renders as
+    // plaintext (so the production build never fails on a single fence) and emits
+    // a one-line console.warn that authors running a clean local build can spot.
+    // The warning dedupes per-process so noisy content doesn't spam the log.
+    resetUnknownLangWarningsForTests();
+    const warn = spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const hast1 = await highlightToHast('x = 1', 'totally-not-a-real-lang');
+      const hast2 = await highlightToHast('y = 2', 'totally-not-a-real-lang');
+      expect(hast1.type).toBe('root');
+      expect(hast2.type).toBe('root');
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0]?.[0]).toMatch(/\[shiki\] Unknown code-block language "totally-not-a-real-lang"/);
+    } finally {
+      warn.mockRestore();
+      mock.restore();
+      // Reset on the way out too so subsequent tests / re-runs don't inherit
+      // the dedup state populated by this test.
+      resetUnknownLangWarningsForTests();
+    }
+  });
+
+  test('empty fence language renders as plaintext without throwing', async () => {
+    const hast = await highlightToHast('plain content', '');
+    expect(hast.type).toBe('root');
+  });
+});

package/src/lib/shiki.ts

@@ -0,0 +1,292 @@
+import {
+  bundledLanguages,
+  bundledLanguagesInfo,
+  createHighlighter,
+  type BundledLanguage,
+  type Highlighter,
+  type ShikiTransformer,
+} from 'shiki';
+import {
+  transformerNotationDiff,
+  transformerNotationErrorLevel,
+  transformerNotationFocus,
+  transformerNotationHighlight,
+} from '@shikijs/transformers';
+import type { Root } from 'hast';
+
+export const SHIKI_THEMES = { light: 'github-light', dark: 'github-dark' } as const;
+
+// Discovery from Shiki's own metadata, not a hand-maintained list. `bundledLanguagesInfo`
+// gives us every canonical id, its proper-case display name, and the aliases Shiki natively
+// understands (e.g. ts/cts/mts → typescript). Building ALIAS_MAP and DISPLAY_MAP once at
+// module init lets us resolve any of Shiki's ~235 bundled languages without curating a list.
+const ALIAS_MAP: Record<string, string> = {};
+const DISPLAY_MAP: Record<string, string> = {};
+for (const info of bundledLanguagesInfo) {
+  ALIAS_MAP[info.id] = info.id;
+  DISPLAY_MAP[info.id] = info.name ?? info.id;
+  for (const alias of info.aliases ?? []) {
+    ALIAS_MAP[alias] = info.id;
+  }
+}
+
+// Amytis-specific overlay. `plaintext` is Shiki's built-in "special" language (always
+// available without a grammar load), but Shiki doesn't list it in bundledLanguagesInfo,
+// so we register it explicitly. The empty-string fence (```\n...\n```) maps to plaintext
+// too. svg/plain/text/txt are our own conventional aliases.
+const PLAINTEXT_DISPLAY = 'Plain text';
+ALIAS_MAP['plaintext'] = 'plaintext';
+ALIAS_MAP['text'] = 'plaintext';
+ALIAS_MAP['txt'] = 'plaintext';
+ALIAS_MAP['plain'] = 'plaintext';
+ALIAS_MAP[''] = 'plaintext';
+ALIAS_MAP['svg'] = ALIAS_MAP['xml'] ?? 'xml';
+DISPLAY_MAP['plaintext'] = PLAINTEXT_DISPLAY;
+
+// Community aliases Shiki doesn't ship as official aliases in bundledLanguagesInfo.
+// Each entry maps a name authors commonly write to a verified-bundled canonical id.
+// Slow-growing list — Shiki's official aliases cover most cases. Extend here when a
+// build hits an unknown-lang throw for a real community-name alias (not a typo).
+const COMMUNITY_ALIASES: Record<string, string> = {
+  golang: 'go',                  // `go` ships without `golang` in Shiki's aliases
+  node: 'javascript',            // node code snippets routinely written as ```node
+  nodejs: 'javascript',
+  'obj-c': 'objective-c',        // Shiki ships `objc` and `objective-c` but not `obj-c`
+  gnumakefile: 'make',           // GNU/BSD-disambiguated makefile names
+  bsdmakefile: 'make',
+};
+for (const [alias, canonical] of Object.entries(COMMUNITY_ALIASES)) {
+  ALIAS_MAP[alias] = canonical;
+}
+
+function resolveCanonical(language: string): string | null {
+  const key = (language || '').toLowerCase();
+  return ALIAS_MAP[key] ?? null;
+}
+
+export function getLanguageDisplayName(language: string): string {
+  const canonical = resolveCanonical(language);
+  if (canonical && DISPLAY_MAP[canonical]) return DISPLAY_MAP[canonical];
+  // Defensive — highlightToHast throws on unknown langs, so this branch
+  // shouldn't trigger at render time. Returns the raw input for safety.
+  return language;
+}
+
+declare global {
+  var __amytisShikiHighlighter: Promise<Highlighter> | undefined;
+}
+
+export function getHighlighter(): Promise<Highlighter> {
+  if (!globalThis.__amytisShikiHighlighter) {
+    // Preload only `plaintext` — Shiki's special always-available lang. Every other
+    // bundled grammar is loaded lazily on first use via ensureLanguageLoaded below.
+    // Drastically smaller cold-start than eagerly loading 20+ grammars.
+    globalThis.__amytisShikiHighlighter = createHighlighter({
+      themes: [SHIKI_THEMES.light, SHIKI_THEMES.dark],
+      langs: ['plaintext'],
+    });
+  }
+  return globalThis.__amytisShikiHighlighter;
+}
+
+export function resetHighlighterForTests(): void {
+  globalThis.__amytisShikiHighlighter = undefined;
+}
+
+async function ensureLanguageLoaded(highlighter: Highlighter, canonical: string): Promise<void> {
+  if (canonical === 'plaintext') return; // Shiki's special lang — always available.
+  if (highlighter.getLoadedLanguages().includes(canonical)) return;
+  const loader = bundledLanguages[canonical as BundledLanguage];
+  if (!loader) return; // Defensive — shouldn't happen since resolveCanonical gates entry.
+  await highlighter.loadLanguage(loader);
+}
+
+export interface ParsedFenceMeta {
+  title?: string;
+  showLineNumbers?: boolean;
+  highlightLines?: number[];
+  tabLabel?: string;
+  raw?: string;
+}
+
+export function parseFenceMeta(meta: string | undefined | null): ParsedFenceMeta {
+  if (!meta) return {};
+  const result: ParsedFenceMeta = { raw: meta };
+
+  // Docusaurus-style [label] at the start of the meta — used by tabbed code groups
+  // to name each tab. Stays harmlessly attached to non-grouped blocks too. Square
+  // brackets are unambiguous against the curly-brace {1,3-5} highlight syntax.
+  const labelMatch = meta.match(/^\s*\[([^\]]+)\]/);
+  if (labelMatch) {
+    // Trim and discard if empty — `[   ]` would otherwise leak an empty-string
+    // label that bypasses downstream `?? language` fallbacks (empty isn't nullish).
+    const label = labelMatch[1].trim();
+    if (label) result.tabLabel = label;
+  }
+
+  const titleMatch = meta.match(/title=(?:"([^"]*)"|'([^']*)')/);
+  if (titleMatch) result.title = titleMatch[1] ?? titleMatch[2] ?? '';
+
+  if (/(?:^|\s)(linenos|showLineNumbers)(?=\s|$)/.test(meta)) {
+    result.showLineNumbers = true;
+  }
+
+  const highlightMatch = meta.match(/\{([\d,\s-]+)\}/);
+  if (highlightMatch) {
+    const expanded = expandLineRanges(highlightMatch[1]);
+    if (expanded.length > 0) result.highlightLines = expanded;
+  }
+
+  return result;
+}
+
+export function expandLineRanges(spec: string): number[] {
+  const seen = new Set<number>();
+  for (const raw of spec.split(',')) {
+    const piece = raw.trim();
+    if (!piece) continue;
+    const range = piece.match(/^(\d+)\s*-\s*(\d+)$/);
+    if (range) {
+      const a = Number(range[1]);
+      const b = Number(range[2]);
+      const [lo, hi] = a <= b ? [a, b] : [b, a];
+      for (let i = lo; i <= hi; i++) seen.add(i);
+    } else if (/^\d+$/.test(piece)) {
+      seen.add(Number(piece));
+    }
+  }
+  return [...seen].sort((a, b) => a - b);
+}
+
+function ensureClassList(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.filter((v) => typeof v === 'string').join(' ');
+  return '';
+}
+
+function addClass(node: { properties?: Record<string, unknown> }, cls: string): void {
+  node.properties = node.properties ?? {};
+  const existing = ensureClassList(node.properties.class);
+  node.properties.class = existing ? `${existing} ${cls}` : cls;
+}
+
+function setProperty(
+  node: { properties?: Record<string, unknown> },
+  key: string,
+  value: string,
+): void {
+  node.properties = node.properties ?? {};
+  node.properties[key] = value;
+}
+
+function transformerLineNumbers(enabled: boolean): ShikiTransformer {
+  return {
+    name: 'amytis:line-numbers',
+    pre(node) {
+      if (enabled) setProperty(node, 'data-line-numbers', 'true');
+    },
+  };
+}
+
+function transformerTitle(title?: string): ShikiTransformer {
+  return {
+    name: 'amytis:title',
+    pre(node) {
+      if (title) setProperty(node, 'data-title', title);
+    },
+  };
+}
+
+function transformerHighlightLines(lines: number[] | undefined): ShikiTransformer {
+  const set = new Set(lines ?? []);
+  return {
+    name: 'amytis:highlight-lines',
+    line(node, lineIdx) {
+      if (set.has(lineIdx)) {
+        addClass(node, 'highlighted');
+        setProperty(node, 'data-highlighted-line', String(lineIdx));
+      }
+    },
+  };
+}
+
+function transformerDiffBg(lang: string, source: string): ShikiTransformer {
+  if (lang !== 'diff') return { name: 'amytis:diff-bg-noop' };
+  const lines = source.split('\n');
+  return {
+    name: 'amytis:diff-bg',
+    line(node, lineIdx) {
+      const text = lines[lineIdx - 1] ?? '';
+      if (text.startsWith('+') && !text.startsWith('+++')) {
+        addClass(node, 'diff add');
+      } else if (text.startsWith('-') && !text.startsWith('---')) {
+        addClass(node, 'diff remove');
+      }
+    },
+  };
+}
+
+export interface HighlightOpts {
+  showLineNumbers?: boolean;
+  highlightLines?: number[];
+  title?: string;
+}
+
+// Module-level dedup so we don't spam build logs when the same unknown lang
+// appears in many posts. Reset between processes; not a leak across builds.
+const warnedUnknownLangs = new Set<string>();
+
+export function resetUnknownLangWarningsForTests(): void {
+  warnedUnknownLangs.clear();
+}
+
+export async function highlightToHast(
+  code: string,
+  language: string,
+  opts: HighlightOpts = {},
+): Promise<Root> {
+  const canonical = resolveCanonical(language);
+  // Soft fallback for unknown fence languages: render as plaintext + warn (deduped).
+  // The CLAUDE.md "strict build over silent runtime failure" principle is correct
+  // for structural misconfiguration (frontmatter, slugs, redirects), but wrong here:
+  // "typo" and "community alias" look identical from our side, and Shiki's alias
+  // coverage is narrower than what blog authors routinely write. Failing a whole
+  // production deploy because one fence used `\`\`\`golang` is worse than the block
+  // rendering as monochrome monospace with a build-time warn. Authors running a
+  // clean local build still see real typos in the warn output.
+  if (!canonical && language && !warnedUnknownLangs.has(language)) {
+    warnedUnknownLangs.add(language);
+    console.warn(
+      `[shiki] Unknown code-block language "${language}" — rendering as plaintext. To fix highlighting, add an entry to COMMUNITY_ALIASES in src/lib/shiki.ts, or use a recognized name. Use \`plaintext\` explicitly to silence this warning.`,
+    );
+  }
+
+  const lang = canonical ?? 'plaintext';
+  const highlighter = await getHighlighter();
+  await ensureLanguageLoaded(highlighter, lang);
+
+  return highlighter.codeToHast(code, {
+    lang,
+    themes: SHIKI_THEMES,
+    defaultColor: false,
+    transformers: [
+      transformerLineNumbers(!!opts.showLineNumbers),
+      transformerTitle(opts.title),
+      transformerHighlightLines(opts.highlightLines),
+      transformerDiffBg(lang, code),
+      // VitePress-style notation comments inside the source:
+      //   // [!code focus]         dim/blur non-focused lines (hover to reveal)
+      //   // [!code error]         red line tinting
+      //   // [!code warning]       amber line tinting
+      //   // [!code highlight]     same .highlighted class as the meta {1,3-5} syntax
+      //   // [!code ++] / [!code --] same .diff.add / .diff.remove classes as the
+      //                            raw +/- transformer in diff fences; they coexist.
+      // The class names emitted (.focused/.error/.warning/.highlighted/.diff.add/.diff.remove)
+      // are styled by globals.css alongside our existing rules.
+      transformerNotationFocus({ classActivePre: 'has-focused' }),
+      transformerNotationErrorLevel(),
+      transformerNotationHighlight(),
+      transformerNotationDiff(),
+    ],
+  });
+}

package/src/lib/urls.ts

@@ -105,3 +105,60 @@ export function getStaticPageUrl(slug: string): string {
 export function getPostUrlInCollection(post: { slug: string; series?: string }, collectionSlug: string): string {
   return `${getPostUrl(post)}?${new URLSearchParams({ collection: collectionSlug }).toString()}`;
 }
+
+let cachedSiteHost: string | null | undefined;
+
+function getSiteHost(): string | null {
+  if (cachedSiteHost !== undefined) return cachedSiteHost;
+  try {
+    cachedSiteHost = new URL(siteConfig.baseUrl).host;
+  } catch {
+    cachedSiteHost = null;
+  }
+  return cachedSiteHost;
+}
+
+/**
+ * True when `href` points to a different host than `siteConfig.baseUrl`.
+ *
+ * - `http://` / `https://` absolute URLs and protocol-relative `//host/...`
+ *   are tested by host comparison.
+ * - `mailto:`, `tel:`, `sms:`, `ftp:`, `javascript:` and other non-http
+ *   schemes return false — they're "external" in spirit but have different
+ *   click semantics and don't warrant an outward-arrow indicator.
+ * - Hash-only (`#foo`), query-only (`?foo`), relative paths (`/foo`,
+ *   `foo.md`), empty strings → false.
+ * - Malformed URLs → false (defensive — don't decorate something we can't parse).
+ */
+export function isExternalUrl(href: string | undefined | null): boolean {
+  if (!href) return false;
+  if (href.startsWith('#') || href.startsWith('?')) return false;
+  if (/^(mailto|tel|sms|ftp|javascript):/i.test(href)) return false;
+
+  const siteHost = getSiteHost();
+  if (!siteHost) return false;
+
+  if (href.startsWith('//')) {
+    // Prefix a dummy scheme so the URL parser handles auth (`//user:pass@host`),
+    // port-only (`//:80`), and IPv6 forms correctly — substring splitting on
+    // `/` is too coarse for any of those.
+    try {
+      return new URL(`https:${href}`).host !== siteHost;
+    } catch {
+      return false;
+    }
+  }
+  if (/^https?:\/\//i.test(href)) {
+    try {
+      return new URL(href).host !== siteHost;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** Test-only: drop the cached site host so a test can re-read `siteConfig.baseUrl`. */
+export function resetSiteHostCacheForTests(): void {
+  cachedSiteHost = undefined;
+}