feat: add rangi plugin + rename highlight to shiki (#332)

Co-authored-by: Sébastien Chopin <atinux@gmail.com>

Author: farnabaz

AGENTS.md

@@ -60,13 +60,21 @@ packages/comark/
 │   │   ├── components.ts     # Block/inline components + spans (`::name`, `:name`, `[text]`)
 │   │   ├── attributes.ts     # Inline attributes (`{props}` after tokens)
 │   │   ├── emoji.ts          # Emoji shortcodes
-│   │   ├── highlight.ts      # Syntax highlighting via Shiki (peer: shiki)
+│   │   ├── shiki.ts          # Syntax highlighting via Shiki (peer: shiki)
+│   │   ├── highlight.ts      # Deprecated alias → shiki (remove next major)
+│   │   ├── rangi.ts          # Lightweight highlighting via rangi (peer: rangi)
 │   │   ├── math.ts           # LaTeX math via KaTeX (peer: katex)
 │   │   ├── mermaid.ts        # Mermaid diagrams (peer: beautiful-mermaid)
 │   │   ├── security.ts       # XSS/security sanitization
 │   │   ├── summary.ts        # Summary extraction
 │   │   ├── task-list.ts      # GFM task lists
 │   │   └── toc.ts            # Table of contents
+│   ├── utils/                # Shared utilities (comark/utils entry point)
+│   │   ├── index.ts          # textContent(), visit(), visitAsync(), string/object utils
+│   │   ├── helpers.ts        # defineComarkPlugin(), dedupePlugins()
+│   │   ├── caret.ts          # Caret utilities for streaming
+│   │   ├── comark.tmLanguage.ts    # Comark TextMate grammar (Shiki plugin)
+│   │   └── comark.rangiLanguage.ts # Comark rangi grammar (rangi plugin)
 │   └── internal/             # Internal implementation (not exported)
 │       ├── front-matter.ts
 │       ├── parse/            # Parsing pipeline
@@ -80,7 +88,8 @@ packages/comark/
 
 | Peer | Required by |
 |------|-------------|
-| `shiki` | `comark/plugins/highlight` |
+| `shiki` | `comark/plugins/shiki` |
+| `rangi` | `comark/plugins/rangi` |
 | `katex` | `comark/plugins/math` |
 | `beautiful-mermaid` | `comark/plugins/mermaid` |
 
@@ -104,12 +113,12 @@ Located at `packages/comark-html/`. Framework-free HTML string rendering.
 
 ```typescript
 import { createHtmlRenderer, renderHtml, renderHtmlFromDocument } from '@comark/html'
-import highlight from '@comark/html/plugins/highlight'
+import shiki from '@comark/html/plugins/shiki'
 import math, { Math } from '@comark/html/plugins/math'
 
 // Flat options — ParserOptions & RendererOptions merged at top level
 const renderHtml = createHtmlRenderer({
-  plugins: [highlight({ themes: { light: 'github-light', dark: 'github-dark' } })],
+  plugins: [shiki({ themes: { light: 'github-light', dark: 'github-dark' } })],
   components: {
     Math,
     alert: async ([, attrs, ...children], { render }) =>
@@ -140,12 +149,12 @@ Located at `packages/comark-ansi/`. ANSI terminal renderer.
 
 ```typescript
 import { createAnsiRenderer, createAnsiWriter, renderAnsi, renderAnsiFromDocument, writeAnsi } from '@comark/ansi'
-import highlight from '@comark/ansi/plugins/highlight'
+import shiki from '@comark/ansi/plugins/shiki'
 import math, { Math } from '@comark/ansi/plugins/math'
 
 // Flat options — ParserOptions & AnsiRendererOptions merged at top level
 const writeAnsi = createAnsiWriter({
-  plugins: [highlight(), math()],
+  plugins: [shiki(), math()],
   components: { Math },
   width: 120,                      // terminal width
   colors: true,                    // emit ANSI escape codes
@@ -379,7 +388,9 @@ import type { MarkdownDocument, Node, ElementNode, TextNode } from 'comark'
 import { textContent, visit } from 'comark/utils'
 
 // Core plugins — use when calling parseMarkdown() directly (framework-agnostic)
-import highlight from 'comark/plugins/highlight'
+import shiki from 'comark/plugins/shiki'
+import rangi, { comarkLanguage, comarkLanguages } from 'comark/plugins/rangi'
+// import highlight from 'comark/plugins/highlight' // deprecated alias → shiki
 import math from 'comark/plugins/math'
 import mermaid from 'comark/plugins/mermaid'
 import emoji from 'comark/plugins/emoji'
@@ -396,18 +407,18 @@ import { markdownItAttributes } from 'comark/plugins/attributes'
 
 // NOTE: All framework packages re-export every core plugin via their own subpath.
 // Prefer the framework-specific path when using a framework renderer:
-//   @comark/vue/plugins/highlight, @comark/react/plugins/highlight, etc.
+//   @comark/vue/plugins/shiki, @comark/react/plugins/shiki, etc.
 // Use comark/plugins/* only when calling parseMarkdown() without a framework renderer.
 
 // HTML rendering — parse + render to HTML string
 import { createHtmlRenderer, renderHtml, renderHtmlFromDocument } from '@comark/html'
-import highlight from '@comark/html/plugins/highlight'
+import shiki from '@comark/html/plugins/shiki'
 import math, { Math } from '@comark/html/plugins/math'
 import mermaid, { Mermaid } from '@comark/html/plugins/mermaid'
 
 // ANSI terminal rendering — parse + render to styled terminal string
 import { createAnsiRenderer, createAnsiWriter, renderAnsi, renderAnsiFromDocument, writeAnsi } from '@comark/ansi'
-import highlight from '@comark/ansi/plugins/highlight'
+import shiki from '@comark/ansi/plugins/shiki'
 import math from '@comark/ansi/plugins/math'
 
 // Vue — renderer + plugin wrappers (plugin fn + Vue component)

benchmarks/plugin-highlight.ts

@@ -4,7 +4,7 @@ import MarkdownExit from 'markdown-exit'
 import { markdownItComponents } from 'comark/plugins/components'
 import { markdownItAttributes } from 'comark/plugins/attributes'
 import { createMarkdownParser } from 'comark'
-import highlight, { getHighlighter } from '../packages/comark/src/plugins/highlight'
+import shiki, { getHighlighter } from '../packages/comark/src/plugins/shiki'
 import { codeToHast } from 'shiki/core'
 
 const short = `
@@ -40,7 +40,7 @@ interface ParserOptions {
 
 const tree = await parseMarkdown(markdown, {
   autoClose: true,
-  plugins: [highlight()],
+  plugins: [shiki()],
 })
 \`\`\`
 
@@ -49,12 +49,12 @@ const tree = await parseMarkdown(markdown, {
 \`\`\`vue
 <script setup>
 import { Markdown } from '@comark/vue'
-import highlight from '@comark/vue/plugins/highlight'
+import shiki from '@comark/vue/plugins/shiki'
 </script>
 
 <template>
   <Suspense>
-    <Markdown :plugins="[highlight()]">{{ content }}</Markdown>
+    <Markdown :plugins="[shiki()]">{{ content }}</Markdown>
   </Suspense>
 </template>
 \`\`\`
@@ -103,12 +103,12 @@ const markdownExit = new MarkdownExit({ html: true, linkify: true })
 
 // comark: baseline vs highlight plugin
 const comark = createMarkdownParser()
-const comarkHl = createMarkdownParser({ plugins: [highlight()] })
+const comarkHl = createMarkdownParser({ plugins: [shiki()] })
 
 // Pre-warm shiki so we benchmark steady-state, not cold-start
 const shiki = await getHighlighter()
 
-// Warm up comark highlight to ensure shiki languages are loaded
+// Warm up comark shiki to ensure shiki languages are loaded
 await comarkHl(medium)
 
 // Helper: extract fence tokens from markdown-it/exit and highlight them with shiki

docs/app/app.config.ts

@@ -104,8 +104,8 @@ export default defineAppConfig({
         title: 'Plugins',
         links: [
           {
-            label: 'Syntax Highlighting',
-            to: '/plugins/built-in/syntax-highlight',
+            label: 'Shiki',
+            to: '/plugins/built-in/shiki',
           },
           {
             label: 'Math',

docs/app/components/ComarkDocs.ts

@@ -3,7 +3,7 @@ import math, { Math } from '@comark/nuxt/plugins/math'
 import mermaid, { Mermaid } from '@comark/nuxt/plugins/mermaid'
 import emoji from '@comark/nuxt/plugins/emoji'
 import ProsePre from './landing/ProsePre.vue'
-import highlight from 'comark/plugins/highlight'
+import shiki from 'comark/plugins/shiki'
 import Python from '@shikijs/langs/python'
 import githubLight from '@shikijs/themes/github-light'
 import githubDark from '@shikijs/themes/github-dark'
@@ -27,7 +27,7 @@ export default defineMarkdownComponent({
   extends: BaseComarkDocs,
   name: 'ComarkDocs',
   plugins: [
-    highlight({
+    shiki({
       languages: [Python],
       themes: {
         light: githubLight,

docs/app/components/Playground.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { parseMarkdown } from 'comark'
-import highlight from '@comark/nuxt/plugins/highlight'
+import shiki from '@comark/nuxt/plugins/shiki'
 import math from '@comark/nuxt/plugins/math'
 import binding from '@comark/nuxt/plugins/binding'
 import emoji from '@comark/nuxt/plugins/emoji'

docs/app/composables/useMDCStream.ts

@@ -1,7 +1,7 @@
 import type { MarkdownDocument, ParserOptions } from 'comark'
 import { readonly, ref, shallowRef } from 'vue'
 import { parseMarkdown } from 'comark'
-import highlight from 'comark/plugins/highlight'
+import shiki from 'comark/plugins/shiki'
 
 export interface MDCStreamState {
   tree: MarkdownDocument
@@ -16,7 +16,7 @@ export interface MDCStreamOptions extends ParserOptions {
   onError?: (error: Error) => void
 }
 
-const plugins = [highlight()]
+const plugins = [shiki()]
 
 /**
  * Vue composable for streaming Comark content parsing

docs/app/pages/play/[...slug].vue

@@ -5,7 +5,7 @@ import { useCompletion } from '@ai-sdk/vue'
 import { createMarkdownParser } from 'comark'
 import jsonRenderer from '@comark/nuxt/plugins/json-render'
 import binding from '@comark/nuxt/plugins/binding'
-import highlight from '@comark/nuxt/plugins/highlight'
+import shiki from '@comark/nuxt/plugins/shiki'
 import math from '@comark/nuxt/plugins/math'
 import emoji from '@comark/nuxt/plugins/emoji'
 import mermaid from '@comark/nuxt/plugins/mermaid'

docs/app/pages/test.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import highlight from 'comark/plugins/highlight'
+import shiki from 'comark/plugins/shiki'
 import resolveComponent from '../utils/components-manifest'
 
 useHead({
@@ -191,7 +191,7 @@ Thanks for trying the **Comark test page**! 🚀
   <UContainer>
     <Markdown
       :components-manifest="resolveComponent"
-      :plugins="[highlight()]"
+      :plugins="[shiki()]"
     >
       {{ markdown }}
     </Markdown>

docs/content/1.getting-started/0.introduction.md

@@ -207,7 +207,7 @@ For detailed, honest comparisons, see [Comark vs MDX](/compare/comark-vs-mdx), [
   First-class support for Vue, React, Svelte, and Angular with dedicated renderers.
   ::
 
-  ::card{icon="i-lucide-palette" title="Syntax Highlighting" to="/plugins/built-in/syntax-highlight"}
+  ::card{icon="i-lucide-palette" title="Syntax Highlighting" to="/plugins/built-in/shiki"}
   Built-in Shiki integration for beautiful code blocks with theme support.
   ::
 

docs/content/1.getting-started/1.installation.md

@@ -224,7 +224,7 @@ const document = await parseMarkdown(source)
 const output = await renderMarkdown(document)
 
 // Reusable parser: initializes plugins once, faster for batch processing
-const parseDoc = createMarkdownParser({ plugins: [highlight(), toc()] })
+const parseDoc = createMarkdownParser({ plugins: [shiki(), toc()] })
 ```
 
 See the [Parse API](/api/parse) and [Render API](/api/render) for full options.