feat(v0.3.0): add Shiki, Docusaurus, and Starlight companion plugins

Three new subpath exports built on top of the core plugin's AST output:

- remark-code-region/shiki — injects [!code highlight]/[!code focus]
  annotations from ?highlight= and ?focus= flags, with language-aware
  comment syntax (# for Python/Bash/Ruby, // for JS/Rust/Go, -- for
  SQL/Lua, /* */ for CSS, <!-- --> for HTML). Optional diffStepStyle:
  'highlight' converts diff-step ++/-- markers into softer highlight
  emphasis. Shiki transformers only recognize annotations inside
  language-valid comments, so the language map is essential.

- remark-code-region/docusaurus — turns tabGroup wrapper nodes into
  <Tabs>/<TabItem> MDX JSX with automatic import injection.

- remark-code-region/starlight — turns tabGroup wrapper nodes into
  Starlight <Tabs>/<TabItem> components with syncKey support.

Core changes:
- parseFlags() extracts highlight=/focus= and stores raw specs on
  node.data for companion plugins to consume.
- New scripts/build.mjs replaces the inline esbuild command and
  builds 4 CJS bundles in parallel.
- CI smoke-tests all 4 CJS bundles.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: patricker

.github/workflows/ci.yml

@@ -29,8 +29,12 @@ jobs:
       - name: Build
         run: npm run build
 
-      - name: Verify CJS bundle
-        run: node -e "const p = require('./index.cjs'); if (typeof p !== 'function') { console.error('CJS export is not a function:', typeof p); process.exit(1); }"
+      - name: Verify CJS bundles
+        run: |
+          node -e "const p = require('./index.cjs'); if (typeof p !== 'function') { console.error('CJS export is not a function:', typeof p); process.exit(1); }"
+          node -e "const p = require('./lib/docusaurus.cjs'); if (typeof p !== 'function') { console.error('CJS export is not a function:', typeof p); process.exit(1); }"
+          node -e "const p = require('./lib/starlight.cjs'); if (typeof p !== 'function') { console.error('CJS export is not a function:', typeof p); process.exit(1); }"
+          node -e "const p = require('./lib/shiki.cjs'); if (typeof p !== 'function') { console.error('CJS export is not a function:', typeof p); process.exit(1); }"
 
       - name: Test
         run: npm test

.gitignore

@@ -1,2 +1,4 @@
 node_modules/
 index.cjs
+lib/*.cjs
+ref/

README.md

@@ -430,7 +430,60 @@ To split adjacent tab groups without visible content between them, use an HTML c
 
 The plugin emits `tabGroup` wrapper nodes with `data.hName = 'div'` and `data.hProperties.class = 'code-tabs'` (customizable via `tabGroupClass` option). Each child code node gets `data.tabLabel` and `data.hProperties['data-tab']`.
 
-Without a companion plugin, this renders as a `<div class="code-tabs">` wrapping stacked `<pre><code>` blocks. Framework-specific companion plugins (coming soon) will transform these into native Docusaurus `<Tabs>`, Starlight tabs, etc.
+Without a companion plugin, this renders as a `<div class="code-tabs">` wrapping stacked `<pre><code>` blocks. Add a companion plugin to transform these into native framework tabs:
+
+**Docusaurus:**
+```js
+const codeRegion = require('remark-code-region');
+const codeRegionTabs = require('remark-code-region/docusaurus');
+
+remarkPlugins: [codeRegion, codeRegionTabs],
+```
+
+**Astro Starlight:**
+```js
+import codeRegion from 'remark-code-region';
+import codeRegionTabs from 'remark-code-region/starlight';
+
+remarkPlugins: [codeRegion, codeRegionTabs],
+```
+
+For other remark pipelines, the `tabGroup` AST nodes are well-structured for custom rehype plugins to consume directly.
+
+## Shiki annotations
+
+Add `?highlight=` or `?focus=` to any reference to inject [Shiki transformer annotations](https://shiki.style/packages/transformers) into the extracted code:
+
+````md
+```python reference="tests/test_sdk.py#create_user?highlight=1,3-5"
+```
+
+```python reference="tests/test_sdk.py#create_user?focus=2,4-6"
+```
+````
+
+Line numbers are 1-based and refer to the final output (after strip/transmute/dedent). Ranges (`3-5`) and mixed specs (`1,3-5,8`) are supported.
+
+Add the Shiki companion plugin to inject the annotations:
+
+```js
+import codeRegion from 'remark-code-region';
+import codeRegionShiki from 'remark-code-region/shiki';
+
+remarkPlugins: [codeRegion, codeRegionShiki],
+```
+
+Requires `@shikijs/transformers` (`transformerNotationHighlight`, `transformerNotationFocus`) configured in your Shiki setup.
+
+### Soft diff-step highlighting
+
+By default, `diff-step` emits `// [!code ++]` / `// [!code --]` for green/red diff highlighting. The Shiki companion can convert these to softer `// [!code highlight]` annotations — emphasizing new lines without the diff color scheme:
+
+```js
+remarkPlugins: [codeRegion, [codeRegionShiki, { diffStepStyle: 'highlight' }]],
+```
+
+Lines marked `// [!code --]` are removed (since diff-step shows the current code state), and `// [!code ++]` becomes `// [!code highlight]`.
 
 ## Auto-dedent
 
@@ -553,15 +606,27 @@ Works inside MDX components (`<Tabs>`, admonitions) -- the plugin runs at the re
 
 ```js
 const codeRegion = require('remark-code-region');
+const codeRegionTabs = require('remark-code-region/docusaurus'); // optional, for tab groups
 
 module.exports = {
   presets: [['classic', {
-    docs: { remarkPlugins: [codeRegion] },
+    docs: { remarkPlugins: [codeRegion, codeRegionTabs] },
   }]],
 };
 ```
 
-### Astro
+### Astro Starlight
+
+```js
+import codeRegion from 'remark-code-region';
+import codeRegionTabs from 'remark-code-region/starlight'; // optional, for tab groups
+
+export default defineConfig({
+  markdown: { remarkPlugins: [codeRegion, codeRegionTabs] },
+});
+```
+
+### Astro (non-Starlight)
 
 ```js
 import codeRegion from 'remark-code-region';

index.mjs

@@ -62,14 +62,16 @@ function fail(vfile, msg) {
  * Parse ?flags from a raw reference value (e.g., "file.py#region?noStrip&format=unified").
  * @param {string} rawValue
  * @param {'unified'|'inline-annotations'|'side-by-side'} defaultFormat
- * @returns {{ flagOverrides: { noStrip: boolean, noTransmute: boolean }, effectiveDiffFormat: string, formatFlag: string|null }}
+ * @returns {{ flagOverrides: { noStrip: boolean, noTransmute: boolean }, effectiveDiffFormat: string, formatFlag: string|null, highlight: string|null, focus: string|null }}
  */
 function parseFlags(rawValue, defaultFormat) {
   const hashIndex = rawValue.indexOf('#');
   const fragStr = hashIndex >= 0 ? rawValue.slice(hashIndex + 1) : null;
   const qIndex = fragStr ? fragStr.indexOf('?') : -1;
   const flags = qIndex >= 0 ? fragStr.slice(qIndex + 1).split('&') : [];
   const formatFlag = flags.find((f) => f.startsWith('format='));
+  const highlightFlag = flags.find((f) => f.startsWith('highlight='));
+  const focusFlag = flags.find((f) => f.startsWith('focus='));
   return {
     flagOverrides: {
       noStrip: flags.includes('noStrip'),
@@ -79,6 +81,8 @@ function parseFlags(rawValue, defaultFormat) {
       ? formatFlag.slice('format='.length)
       : defaultFormat,
     formatFlag: formatFlag || null,
+    highlight: highlightFlag ? highlightFlag.slice('highlight='.length) : null,
+    focus: focusFlag ? focusFlag.slice('focus='.length) : null,
   };
 }
 
@@ -431,10 +435,13 @@ export default function remarkCodeRegion(options = {}) {
         primaryResolveDir = file?.dirname || file?.cwd || process.cwd();
       }
 
-      const { flagOverrides, effectiveDiffFormat, formatFlag } = parseFlags(
-        primaryRaw,
-        diffFormat,
-      );
+      const {
+        flagOverrides,
+        effectiveDiffFormat,
+        formatFlag,
+        highlight,
+        focus,
+      } = parseFlags(primaryRaw, diffFormat);
 
       const primary = resolveRef(
         primaryRaw,
@@ -469,6 +476,12 @@ export default function remarkCodeRegion(options = {}) {
       }
 
       node.meta = cleanMeta(node.meta, isFileDirective, preserveFileMeta);
+
+      if (highlight || focus) {
+        node.data = node.data || {};
+        if (highlight) node.data.highlight = highlight;
+        if (focus) node.data.focus = focus;
+      }
     });
 
     // Pass 2: group consecutive tab= fences into tabGroup wrapper nodes

lib/docusaurus.d.mts

@@ -0,0 +1,11 @@
+import type { Plugin } from 'unified';
+
+export interface DocusaurusOptions {
+  /** Import path for Tabs component. Default: '@theme/Tabs'. */
+  tabsImport?: string;
+  /** Import path for TabItem component. Default: '@theme/TabItem'. */
+  tabItemImport?: string;
+}
+
+declare const remarkCodeRegionDocusaurus: Plugin<[DocusaurusOptions?]>;
+export default remarkCodeRegionDocusaurus;

lib/docusaurus.mjs

@@ -0,0 +1,99 @@
+/**
+ * Companion plugin for Docusaurus.
+ *
+ * Transforms `tabGroup` AST nodes into Docusaurus `<Tabs>` / `<TabItem>`
+ * MDX JSX elements with `groupId` for synchronized tab switching.
+ *
+ * Usage:
+ *   import codeRegion from 'remark-code-region';
+ *   import codeRegionTabs from 'remark-code-region/docusaurus';
+ *   remarkPlugins: [codeRegion, codeRegionTabs],
+ */
+
+import { visit } from 'unist-util-visit';
+
+function slugify(label) {
+  const slug = label
+    .toLowerCase()
+    .replace(/\+/g, 'p')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  return slug || `tab-${label.length}`;
+}
+
+function attr(name, value) {
+  return { type: 'mdxJsxAttribute', name, value };
+}
+
+export default function remarkCodeRegionDocusaurus(options = {}) {
+  const { tabsImport = '@theme/Tabs', tabItemImport = '@theme/TabItem' } =
+    options;
+
+  return (tree) => {
+    let hasTabGroups = false;
+
+    visit(tree, 'tabGroup', (node, index, parent) => {
+      hasTabGroups = true;
+
+      const syncKey = node.data?.hProperties?.['data-tab-group'] || null;
+      const children = node.children || [];
+
+      const tabItems = children.map((child) => {
+        const label = child.data?.tabLabel || 'Code';
+        const value = slugify(label);
+
+        const attributes = [attr('value', value), attr('label', label)];
+
+        return {
+          type: 'mdxJsxFlowElement',
+          name: 'TabItem',
+          attributes,
+          children: [child],
+        };
+      });
+
+      const tabsAttrs = [];
+      if (syncKey) {
+        tabsAttrs.push(attr('groupId', syncKey));
+      }
+      if (tabItems.length > 0) {
+        const firstValue = tabItems[0].attributes.find(
+          (a) => a.name === 'value',
+        )?.value;
+        if (firstValue) {
+          tabsAttrs.push(attr('defaultValue', firstValue));
+        }
+      }
+
+      const tabsNode = {
+        type: 'mdxJsxFlowElement',
+        name: 'Tabs',
+        attributes: tabsAttrs,
+        children: tabItems,
+      };
+
+      parent.children[index] = tabsNode;
+    });
+
+    if (hasTabGroups) {
+      injectImport(tree, tabsImport, tabItemImport);
+    }
+  };
+}
+
+function injectImport(tree, tabsImport, tabItemImport) {
+  const alreadyImported = tree.children.some(
+    (node) =>
+      node.type === 'mdxjsEsm' &&
+      node.value &&
+      (node.value.includes(`'${tabsImport}'`) ||
+        node.value.includes(`"${tabsImport}"`)),
+  );
+  if (alreadyImported) return;
+
+  tree.children.unshift({
+    type: 'mdxjsEsm',
+    value: `import Tabs from '${tabsImport}';\nimport TabItem from '${tabItemImport}';`,
+    data: { estree: null },
+  });
+}

lib/shiki.d.mts

@@ -0,0 +1,9 @@
+import type { Plugin } from 'unified';
+
+export interface ShikiOptions {
+  /** Convert diff-step // [!code ++] to // [!code highlight] and remove // [!code --] lines. */
+  diffStepStyle?: 'highlight';
+}
+
+declare const remarkCodeRegionShiki: Plugin<[ShikiOptions?]>;
+export default remarkCodeRegionShiki;