{"_id":"@aero-js/highlight","_rev":"4-a01b9dacc81cd72975997e1b6a28c3f6","name":"@aero-js/highlight","dist-tags":{"latest":"0.4.0"},"versions":{"0.3.3":{"name":"@aero-js/highlight","version":"0.3.3","author":{"name":"Jamie Wilson"},"license":"MIT","_id":"@aero-js/highlight@0.3.3","maintainers":[{"name":"jmwlsn","email":"jamie@jamiewilson.io"}],"homepage":"https://github.com/jamiewilson/aero","bugs":{"url":"https://github.com/jamiewilson/aero/issues"},"dist":{"shasum":"e97845b07f45d090ac2ff3275da4dcd09d32c4b4","tarball":"https://registry.npmjs.org/@aero-js/highlight/-/highlight-0.3.3.tgz","fileCount":5,"integrity":"sha512-0UFGqKA1qrYR5e0Htb9r0pqKGeIvfivGL8dNf5HFezbxD1xH+Vcu2OxhPe9tDcBJxU/Nm36CYgpTYXJiP7zjIA==","signatures":[{"sig":"MEUCICM3p+kLrzisR51pwNqGlDgasmcBXgdkheuIck3cjzYcAiEA8RST0MkocFIEDKRXLz7qOhSt651taw3YsL/5aPxkpeY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20578},"type":"module","_from":"file:aero-js-highlight-0.3.3.tgz","types":"./dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"./types":"./dist/index.d.mts"},"private":false,"scripts":{"test":"vitest run","build":"tsdown src/index.ts --format esm --dts --clean --out-dir dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"jmwlsn","email":"jamie@jamiewilson.io"},"_resolved":"/private/var/folders/yc/828p39ws2lxgqcb96h4qdbjm0000gn/T/b19b1e0a952c6802f24c1e4476d2ba2d/aero-js-highlight-0.3.3.tgz","_integrity":"sha512-0UFGqKA1qrYR5e0Htb9r0pqKGeIvfivGL8dNf5HFezbxD1xH+Vcu2OxhPe9tDcBJxU/Nm36CYgpTYXJiP7zjIA==","repository":{"url":"git+https://github.com/jamiewilson/aero.git","type":"git","directory":"packages/highlight"},"_npmVersion":"10.9.3","description":"Shared Shiki syntax highlighting utility for the Aero framework.","directories":{},"_nodeVersion":"22.18.0","dependencies":{"shiki":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.21.0-beta.2","vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^25.3.0","@shikijs/transformers":"^3.0.0"},"peerDependencies":{"@shikijs/transformers":"^3.0.0"},"peerDependenciesMeta":{"@shikijs/transformers":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/highlight_0.3.3_1772817330852_0.06789043480996826","host":"s3://npm-registry-packages-npm-production"}},"0.3.4":{"name":"@aero-js/highlight","version":"0.3.4","author":{"name":"Jamie Wilson"},"license":"MIT","_id":"@aero-js/highlight@0.3.4","maintainers":[{"name":"jmwlsn","email":"jamie@jamiewilson.io"}],"homepage":"https://github.com/jamiewilson/aero","bugs":{"url":"https://github.com/jamiewilson/aero/issues"},"dist":{"shasum":"b524ebc9f28e0abc97ac309b13a027b42b31510a","tarball":"https://registry.npmjs.org/@aero-js/highlight/-/highlight-0.3.4.tgz","fileCount":5,"integrity":"sha512-TUlrQnuA9Bnn/jXmll9Lb70dwUU+fpmJ4zRL01n6S84uSA2EaszY2Q8nRYqFeu7zTE2StGXRiZQU0ucmk8+pOQ==","signatures":[{"sig":"MEQCIAbCIm9T5uvzBkytm+1AS32Y4mj6HihTzuvkymFS3Cx4AiArg0Bh7n6dyV8R5aFKnBiLsuzC4cgyazpU4IQ0S66aag==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20576},"type":"module","_from":"file:aero-js-highlight-0.3.4.tgz","types":"./dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"./types":"./dist/index.d.mts"},"private":false,"scripts":{"test":"vitest run","build":"tsdown src/index.ts --format esm --dts --clean --out-dir dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"jmwlsn","email":"jamie@jamiewilson.io"},"_resolved":"/private/var/folders/yc/828p39ws2lxgqcb96h4qdbjm0000gn/T/91e6617250a16336329a0b5eb4e9a72f/aero-js-highlight-0.3.4.tgz","_integrity":"sha512-TUlrQnuA9Bnn/jXmll9Lb70dwUU+fpmJ4zRL01n6S84uSA2EaszY2Q8nRYqFeu7zTE2StGXRiZQU0ucmk8+pOQ==","repository":{"url":"git+https://github.com/jamiewilson/aero.git","type":"git","directory":"packages/highlight"},"_npmVersion":"10.9.3","description":"Shared Shiki syntax highlighting utility for the Aero framework.","directories":{},"_nodeVersion":"22.18.0","dependencies":{"shiki":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.21.0-beta.2","vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^25.3.0","@shikijs/transformers":"^3.0.0"},"peerDependencies":{"@shikijs/transformers":"^3.0.0"},"peerDependenciesMeta":{"@shikijs/transformers":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/highlight_0.3.4_1773676589439_0.352225280319046","host":"s3://npm-registry-packages-npm-production"}},"0.3.5":{"name":"@aero-js/highlight","version":"0.3.5","author":{"name":"Jamie Wilson"},"license":"MIT","_id":"@aero-js/highlight@0.3.5","maintainers":[{"name":"jmwlsn","email":"jamie@jamiewilson.io"}],"homepage":"https://github.com/jamiewilson/aero","bugs":{"url":"https://github.com/jamiewilson/aero/issues"},"dist":{"shasum":"63a6f63476e5a814df1ad5154f685324e4024809","tarball":"https://registry.npmjs.org/@aero-js/highlight/-/highlight-0.3.5.tgz","fileCount":5,"integrity":"sha512-54+xA2LgNP+dMr0KJ4hAfyS517SFwsoQB2OfIAl5pEZe+WhHoZo5jhJkp2aHX/J8jNeE9naLDy5jMzHmlfNngw==","signatures":[{"sig":"MEYCIQDsGKFLq5iVJhgAKaxHhGyRW1GYNHFrQEB6j/EQ65MRIAIhALSwmSMyhygDj2H9kEko/tEQkJHpMmt+4fOSrej+VHCv","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24039},"type":"module","_from":"file:aero-js-highlight-0.3.5.tgz","types":"./dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"./types":"./dist/index.d.mts"},"private":false,"scripts":{"test":"vitest run","build":"tsdown src/index.ts --format esm --dts --clean --out-dir dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"jmwlsn","email":"jamie@jamiewilson.io"},"_resolved":"/private/var/folders/yc/828p39ws2lxgqcb96h4qdbjm0000gn/T/d607219b3b70e3385e44ed2f1e1f7936/aero-js-highlight-0.3.5.tgz","_integrity":"sha512-54+xA2LgNP+dMr0KJ4hAfyS517SFwsoQB2OfIAl5pEZe+WhHoZo5jhJkp2aHX/J8jNeE9naLDy5jMzHmlfNngw==","repository":{"url":"git+https://github.com/jamiewilson/aero.git","type":"git","directory":"packages/highlight"},"_npmVersion":"10.9.3","description":"Shared Shiki syntax highlighting utility for the Aero framework.","directories":{},"_nodeVersion":"22.18.0","dependencies":{"shiki":"^3.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.21.0-beta.2","vitest":"^4.0.18","typescript":"^5.9.3","@types/node":"^25.3.0","@shikijs/transformers":"^3.0.0"},"peerDependencies":{"@shikijs/transformers":"^3.0.0"},"peerDependenciesMeta":{"@shikijs/transformers":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/highlight_0.3.5_1773848978359_0.98197904984753","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@aero-js/highlight","version":"0.4.0","private":false,"homepage":"https://github.com/jamiewilson/aero","license":"MIT","author":{"name":"Jamie Wilson"},"repository":{"type":"git","url":"git+https://github.com/jamiewilson/aero.git","directory":"packages/highlight"},"type":"module","types":"./dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"./types":"./dist/index.d.mts"},"dependencies":{"shiki":"^4.0.2"},"devDependencies":{"@shikijs/transformers":"^4.0.2","@types/node":"^25.5.0","tsdown":"^0.21.7","typescript":"^6.0.2","vitest":"^4.1.2"},"peerDependencies":{"@shikijs/transformers":"^3.0.0"},"peerDependenciesMeta":{"@shikijs/transformers":{"optional":true}},"scripts":{"build":"tsdown src/index.ts --format esm --dts --clean --out-dir dist","typecheck":"tsc --noEmit","test":"vitest run"},"_id":"@aero-js/highlight@0.4.0","description":"Shared Shiki syntax highlighting utility for the Aero framework.","bugs":{"url":"https://github.com/jamiewilson/aero/issues"},"_integrity":"sha512-Opdt3lzgkuRsl28yKw74Eiri2n/ScZh2FeHnHZVKb75PeVTxo+zDpUfk2DhNjFxcnE1l8I/X+/69ufa02o+TsA==","_resolved":"/private/var/folders/yc/828p39ws2lxgqcb96h4qdbjm0000gn/T/32075a7efccab6158b3475e17aac01d6/aero-js-highlight-0.4.0.tgz","_from":"file:aero-js-highlight-0.4.0.tgz","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-Opdt3lzgkuRsl28yKw74Eiri2n/ScZh2FeHnHZVKb75PeVTxo+zDpUfk2DhNjFxcnE1l8I/X+/69ufa02o+TsA==","shasum":"1f48f7c5def8fc5cc77cbf25b87bcfde79fc86ab","tarball":"https://registry.npmjs.org/@aero-js/highlight/-/highlight-0.4.0.tgz","fileCount":5,"unpackedSize":24696,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC+G5MXSCFVFiKtXCyWiFPy6iCBY80FquyT+WwEL4IgOAiBozqt8akksgVocG9Ukw3BxNqxAGiRF0S1/0zhUPOF8tw=="}]},"_npmUser":{"name":"jmwlsn","email":"jamie@jamiewilson.io"},"directories":{},"maintainers":[{"name":"jmwlsn","email":"jamie@jamiewilson.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/highlight_0.4.0_1777591020234_0.7874007631111437"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-06T17:15:30.727Z","modified":"2026-04-30T23:17:00.531Z","0.3.3":"2026-03-06T17:15:31.117Z","0.3.4":"2026-03-16T15:56:29.581Z","0.3.5":"2026-03-18T15:49:38.504Z","0.4.0":"2026-04-30T23:17:00.398Z"},"bugs":{"url":"https://github.com/jamiewilson/aero/issues"},"author":{"name":"Jamie Wilson"},"license":"MIT","homepage":"https://github.com/jamiewilson/aero","repository":{"type":"git","url":"git+https://github.com/jamiewilson/aero.git","directory":"packages/highlight"},"description":"Shared Shiki syntax highlighting utility for the Aero framework.","maintainers":[{"name":"jmwlsn","email":"jamie@jamiewilson.io"}],"readme":"# @aero-js/highlight\n\nShared Shiki syntax highlighting utility for the Aero framework.\n\nProvides composable, reusable Shiki integration across the Aero ecosystem:\n\n- **Markdown code blocks** via `@aero-js/content` (opt-in)\n- **Custom usage** in templates or CLI tools (direct import)\n\n## Installation\n\n```bash\npnpm add @aero-js/highlight\n```\n\n## Usage\n\n### With @aero-js/content (Markdown Highlighting)\n\nWhen using `@aero-js/content`, enable Shiki highlighting by adding `@shikijs/rehype` to `markdown.rehypePlugins` in your `content.config.ts`. Use `@aero-js/highlight` for `addPreDataLang()` (adds `data-lang` on `<pre>`) and for shared config types:\n\n````typescript\n// content.config.ts\nimport { defineCollection, defineConfig } from '@aero-js/content'\nimport { addPreDataLang } from '@aero-js/highlight'\nimport rehypeShiki from '@shikijs/rehype'\nimport { transformerNotationHighlight, transformerNotationFocus } from '@shikijs/transformers'\nimport { z } from 'zod'\n\nconst docs = defineCollection({\n\tname: 'docs',\n\tdirectory: 'content/docs',\n\tschema: z.object({\n\t\ttitle: z.string(),\n\t\tpublished: z.boolean().default(false),\n\t}),\n})\n\nexport default defineConfig({\n\tcollections: [docs],\n\tmarkdown: {\n\t\trehypePlugins: [\n\t\t\t[\n\t\t\t\trehypeShiki,\n\t\t\t\t{\n\t\t\t\t\tthemes: { light: 'github-light', dark: 'github-dark' },\n\t\t\t\t\ttransformers: [\n\t\t\t\t\t\taddPreDataLang(), // Adds data-lang=\"...\" on <pre>\n\t\t\t\t\t\ttransformerNotationHighlight(), // Highlight lines: ```js {1-3}\n\t\t\t\t\t\ttransformerNotationFocus(), // Focus lines: ```js /focus/\n\t\t\t\t\t],\n\t\t\t\t},\n\t\t\t],\n\t\t],\n\t},\n})\n````\n\nAll fenced code blocks in your markdown files will be highlighted. The content pipeline is always `remark` → `remark-rehype` → `[rehypePlugins]` → `rehype-stringify`; without any rehype plugins, code blocks render as plain `<pre><code>`.\n\n````markdown\n```js\nconst greeting = 'Hello, Shiki!'\nconsole.log(greeting)\n```\n````\n\nBecomes:\n\n```html\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"...\">\n  <code>\n    <span class=\"line\"><span style=\"...\">const</span> <span style=\"...\">greeting</span> ...</span>\n    <!-- highlighted tokens -->\n  </code>\n</pre>\n```\n\n### Standalone Usage (Direct Import)\n\nUse `@aero-js/highlight` directly for one-off highlighting in any context:\n\n```typescript\nimport { highlight, addPreDataLang } from '@aero-js/highlight'\n\nconst html = await highlight('const x = 1', 'js', {\n\tthemes: { light: 'github-light', dark: 'github-dark' },\n\ttransformers: [addPreDataLang()],\n})\n\nconsole.log(html)\n// => <pre class=\"shiki ...\" data-lang=\"js\"><code>...</code></pre>\n```\n\n### Single Theme Mode\n\nUse `theme` instead of `themes` for single-theme output:\n\n```typescript\nconst html = await highlight('const x = 1', 'js', {\n\ttheme: 'nord',\n})\n```\n\n### Caching & Performance\n\nThe highlighter is cached at the module level and reused across renders for performance:\n\n```typescript\nimport { getHighlighter } from '@aero-js/highlight'\n\nconst config = {\n\ttheme: 'github-light',\n\tlangs: ['js', 'ts'],\n}\n\n// First call initializes and caches the highlighter\nconst h1 = await getHighlighter(config)\n\n// Subsequent calls with same config return the cached instance\nconst h2 = await getHighlighter(config)\nconsole.log(h1 === h2) // true — same instance\n```\n\n## API\n\n### `highlight(code, language, config): Promise<string>`\n\nHighlight a code string and return highlighted HTML.\n\n**Parameters:**\n\n- `code` - Source code to highlight\n- `language` - Language ID (e.g., `'js'`, `'python'`)\n- `config` - Shiki configuration object\n\n**Returns:** Promise resolving to highlighted HTML string\n\n### `getHighlighter(config): Promise<Highlighter>`\n\nGet or create a cached Shiki highlighter instance. The highlighter is cached at the module level and reused across calls with the same config.\n\n**Parameters:**\n\n- `config` - Shiki configuration object\n\n**Returns:** Promise resolving to a Shiki highlighter instance\n\n### `resetHighlighter(): void`\n\nClear the cached highlighter. Useful for testing to ensure a fresh instance between tests.\n\n## Configuration\n\nThe `ShikiConfig` type wraps Shiki's standard options with full `BundledTheme` and `BundledLanguage` autocomplete.\n\n```typescript\nimport type { ShikiConfig } from '@aero-js/highlight'\n\n// Single theme\nconst single: ShikiConfig = {\n\ttheme: 'github-light',\n\tlangs: ['js', 'ts', 'html', 'css'],\n}\n\n// Multiple themes (light/dark or more)\nconst dual: ShikiConfig = {\n\tthemes: {\n\t\tlight: 'github-light',\n\t\tdark: 'github-dark',\n\t},\n\t// Optional: control which theme gets inline color\n\tdefaultColor: 'light', // 'light' | 'dark' | false | 'light-dark()'\n\t// Optional: CSS variable prefix for theme colors\n\tcssVariablePrefix: '--shiki-',\n\tlangs: ['python', 'rust', 'go'],\n\ttransformers: [\n\t\ttransformerNotationHighlight(), // {1-3}\n\t\ttransformerNotationFocus(), // /focus/\n\t],\n}\n```\n\n### Available Themes\n\nSee [Shiki Themes](https://shiki.style/themes) for the full list. Popular options:\n\n- `github-light` / `github-dark`\n- `nord` / `nord`\n- `vitesse-light` / `vitesse-dark`\n- `dracula` / `dracula`\n\n### Available Languages\n\nSee [Shiki Languages](https://shiki.style/languages) for the full list. Common IDs:\n\n- `js`, `ts`, `jsx`, `tsx` (JavaScript/TypeScript)\n- `html`, `css`, `json`\n- `python`, `rust`, `go`\n- `bash`, `sh`, `zsh`\n- `yaml`, `toml`, `xml`\n- ...and 100+ more\n\n### Aero HTML (use `html`)\n\nThe `aeroHtml` extends HTML with highlighting for JavaScript/TypeScript inside `{ }` expressions in attribute values (e.g. `props=\"{ title: site.title }\"`). It registers as an alias of `html`, so use standard ` ```html ` in markdown. Add `aeroHtml` to `langs` **at the end of the array**:\n\n```typescript\nimport { addPreDataLang, aeroHtml } from '@aero-js/highlight'\nimport rehypeShiki from '@shikijs/rehype'\n\nrehypeShiki({\n\tthemes: { light: 'github-light', dark: 'github-dark' },\n\tlangs: ['js', 'ts', 'html', 'css', 'json', 'bash', aeroHtml],\n\ttransformers: [addPreDataLang()],\n})\n```\n\n**Order matters:** `aeroHtml` aliases to `html`, so when both are in `langs`, Shiki uses the last-registered handler for ` ```html ` blocks. Putting `aeroHtml` last ensures fenced blocks tagged ` ```html ` use the extended grammar (with `{ }` expression highlighting) instead of the base HTML grammar.\n\nThen use ` ```html ` in markdown (no need for `aero-html`):\n\n````markdown\n```html\n<my-component props=\"{ title: site.title, subtitle: site.tagline }\" />\n```\n````\n\n### Transformers\n\nTransformers post-process highlighted code to add features like line highlighting, line numbers, and diffs.\n\n```typescript\nimport { addPreDataLang } from '@aero-js/highlight'\nimport {\n\ttransformerNotationHighlight,\n\ttransformerNotationFocus,\n\ttransformerRenderWhitespace,\n\ttransformerLineNumbers,\n} from '@shikijs/transformers'\n\nconst config = {\n\ttheme: 'github-light',\n\ttransformers: [\n\t\taddPreDataLang(), // Adds data-lang=\"...\" on <pre>\n\t\ttransformerNotationHighlight(), // Highlight lines: [!code highlight]\n\t\ttransformerNotationFocus(), // Focus code: [!code focus]\n\t\ttransformerRenderWhitespace(), // Render whitespace\n\t\ttransformerLineNumbers(), // Add line numbers\n\t],\n}\n```\n\n`addPreDataLang()` uses the raw requested language token (including aliases), so a fenced block tagged as `my-js` emits `data-lang=\"my-js\"`.\n\nSee [Shiki Transformers](https://shiki.style/guide/transformers) for all available transformers and usage.\n\n## Styling\n\nShiki generates semantic HTML with inline styles and CSS classes. The framework does **not** inject CSS — you control styling in your own stylesheets.\n\n**Recommended user stylesheet** (e.g., `src/assets/styles/syntax.css`):\n\n```css\n/* Light theme (default) */\n.shiki {\n\tbackground-color: #f6f8fa;\n\tcolor: #24292e;\n\toverflow-x: auto;\n\tpadding: 1rem;\n\tborder-radius: 0.375rem;\n\tfont-family: 'Menlo', 'Monaco', monospace;\n\tfont-size: 0.875rem;\n\tline-height: 1.5;\n\tmargin: 1rem 0;\n}\n\n/* Dark theme (when root has .dark class) */\n.dark .shiki {\n\tbackground-color: #0d1117;\n\tcolor: #c9d1d9;\n}\n```\n\nImport in your layout:\n\n```html\n<html :class=\"{ dark: isDarkMode }\">\n\t<head>\n\t\t<link rel=\"stylesheet\" href=\"@styles/syntax.css\" />\n\t</head>\n\t<!-- ... -->\n</html>\n```\n\n## Examples\n\n### Markdown with Transformers\n\nIn your `content.config.ts`, add `rehypeShiki` to `markdown.rehypePlugins` with `transformers`:\n\n```typescript\nmarkdown: {\n\trehypePlugins: [\n\t\t[\n\t\t\trehypeShiki,\n\t\t\t{\n\t\t\t\tthemes: { light: 'github-light', dark: 'github-dark' },\n\t\t\t\ttransformers: [transformerNotationHighlight()],\n\t\t\t},\n\t\t],\n\t],\n},\n```\n\nIn your markdown:\n\n````markdown\n```js\nconst x = 1 // [!code highlight]\nconst y = 2\n```\n````\n\n### Custom Component in Templates\n\n```html\n<!-- src/components/code-block.html -->\n<script is:build>\n\timport { highlight } from '@aero-js/highlight'\n\n\tconst { code, language = 'js' } = Aero.props\n\n\tconst html = await highlight(code, language, {\n\t\tthemes: { light: 'github-light', dark: 'github-dark' },\n\t})\n</script>\n\n<pre class=\"code-block\">\n\t{ html }\n</pre>\n\n<style>\n\t.code-block :global(.shiki) {\n\t\tpadding: 1rem;\n\t\tborder-radius: 0.375rem;\n\t}\n</style>\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}