tiptap-extension-shiki 1.0.0

package/.github/workflows/publish_npm.yml

@@ -0,0 +1,32 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      # 触发ci/cd的代码分支
+      - master
+
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-latest
+    # 必须添加这个权限，否则无法获取临时身份证明
+    permissions:
+      contents: read
+      id-token: write 
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          # 注意：这里不再需要配置 registry-url 或 NODE_AUTH_TOKEN
+          
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish to NPM
+        # 使用专用 Action，它会自动识别 OIDC 身份并完成发布
+        run: npm publish --provenance --access public

package/README.md

@@ -0,0 +1,146 @@
+# Tiptap Extension Shiki
+
+[📖 View Chinese Version](./README_CN.md)
+
+### Installation
+
+```bash
+npm install shiki tiptap-extension-shiki
+```
+
+### Usage
+
+```typescript
+new Editor({
+  content: "",
+  extensions: [
+    TiptapShiki.configure({
+      // Must have a default theme for fallback
+      defaultTheme: "dracula",
+      // Must have a default language for fallback
+      defaultLanguage: "javascript",
+      // Since the renderer is asynchronous, the highlighter instance must be passed in the extension configuration
+      highlighter: await createHighlighter({
+        // You can only use the themes and languages loaded by your highlighter, otherwise it will throw an error
+        // Since the main purpose is to provide it for background editor usage, I won't consider asynchronously loading additional languages and themes
+        themes: ["dracula", "dark-plus"],
+        langs: ["javascript", "typescript", "html", "css", "python", "json"],
+      }),
+    }),
+    StarterKit.configure({
+      codeBlock: false,
+    }),
+  ],
+});
+```
+
+### Tiptap getHTML Returns Highlighted HTML
+
+```typescript
+TiptapShiki.configure({
+  // After passing the configuration, using tiptap's getHTML will return highlighted HTML
+  // Note: If getHighlighHTML is enabled, the returned HTML cannot be used for setContent backfill, so please store getJSON for editing, and use HTML only for frontend display
+  getHighlighHTML: true,
+}),
+```
+
+### Custom Toolbar
+
+```typescript
+// You can import the built-in stylesheet or write your own styles
+import "tiptap-extension-shiki/dist/style.css";
+
+TiptapShiki.configure({
+  renderToolbar: ({ language, theme, toolbarDOM, setTheme, setLanguage }) => {
+    // Here, you can insert DOM elements into toolbarDOM in your own way (React/VUE).
+    // For example, you can use renderer(VNode,toolbarDOM)
+
+    // Example: Create toolbar using native DOM
+    // Create language selection dropdown
+    const languageSelect = document.createElement("select");
+    languageSelect.style.cssText =
+      "width: 200px; padding: 4px 8px; margin-right: 8px;";
+    languageSelect.innerHTML = `
+            <option value="javascript">JavaScript</option>
+            <option value="typescript">TypeScript</option>
+            <option value="html">HTML</option>
+            <option value="css">CSS</option>
+            <option value="python">Python</option>
+            <option value="json">JSON</option>
+            <option value="c++">C++</option>
+          `;
+
+    // Create theme selection dropdown
+    const themeSelect = document.createElement("select");
+    themeSelect.style.cssText = "width: 200px; padding: 4px 8px;";
+    themeSelect.innerHTML = `
+            <option value="dracula">Dracula</option>
+            <option value="dark-plus">DarkPlus</option>
+          `;
+
+    // Add language change event listener
+    languageSelect.addEventListener("change", (event) => {
+      // Set selected language
+      setLanguage((event.target as HTMLSelectElement).value);
+    });
+
+    // Add theme change event listener
+    themeSelect.addEventListener("change", (event) => {
+      // Set selected theme
+      setTheme((event.target as HTMLSelectElement).value);
+    });
+
+    // Add DOM elements to toolbar container
+    toolbarDOM.appendChild(languageSelect);
+    toolbarDOM.appendChild(themeSelect);
+  },
+});
+```
+
+### Features
+
+- ✨ Support for multiple programming languages
+- 🎨 Support for multiple theme switching
+- 🛠️ Customizable toolbar interface
+- 🚀 Real-time syntax highlighting rendering
+- 🔧 High-performance syntax highlighting engine based on Shiki
+
+### Configuration Options
+
+| Option             | Type          | Default         | Description                          |
+| ----------------- | ------------- | -------------- | ------------------------------------ |
+| `defaultTheme`    | `string`      | `'dracula'`    | Default syntax highlighting theme (Required) |
+| `defaultLanguage` | `string`      | `'javascript'` | Default programming language (Required)     |
+| `highlighter`     | `Highlighter` | `undefined`    | Shiki highlighter instance (Required)       |
+| `getHighlighHTML` | `boolean`     | `false`        | Whether to generate static highlighted HTML |
+| `renderToolbar`   | `function`    | `undefined`    | Custom toolbar rendering function            |
+
+### Custom Styling
+
+You can customize the appearance of code blocks through CSS:
+
+```css
+.tiptap-shiki--container {
+  border-radius: 8px;
+  font-family: "Fira Code", monospace;
+}
+
+.tiptap-shiki--toolbar {
+  background: rgba(0, 0, 0, 0.05);
+  border-radius: 6px 6px 0 0;
+}
+```
+
+### Contributing
+This plugin references the original highlighting plugin
+[extension-code-block-lowlight](https://github.com/ueberdosis/tiptap/tree/main/packages/extension-code-block-lowlight)
+
+### Notes
+
+1. You must create and configure a Shiki highlighter instance before use
+2. DOM operations in custom toolbar functions are safe, the editor will handle conflicts
+3. Make sure to install all dependencies before use
+
+### License
+
+MIT License

package/README_CN.md

@@ -0,0 +1,146 @@
+# Tiptap Shiki 语法高亮扩展
+
+[📖 View English Version](./README.md)
+
+### 安装
+
+```bash
+npm install shiki tiptap-extension-shiki
+```
+
+### 使用方法
+
+```typescript
+new Editor({
+  content: "",
+  extensions: [
+    TiptapShiki.configure({
+      // 必须有一个默认主题来进行回退
+      defaultTheme: "dracula",
+      // 必须有一个默认语言来进行回退
+      defaultLanguage: "javascript",
+      // 由于渲染器是异步的，所以必须在扩展配置中传递高亮器实例
+      highlighter: await createHighlighter({
+        // 你只能使用你高亮器加载的主题和语言，否则会报错
+        // 因为主要目的是提供给后台的编辑器使用所以我不会考虑异步去加载额外的语言和主题
+        themes: ["dracula", "dark-plus"],
+        langs: ["javascript", "typescript", "html", "css", "python", "json"],
+      }),
+    }),
+    StarterKit.configure({
+      codeBlock: false,
+    }),
+  ],
+});
+```
+
+### Tiptap getHTML 返回高亮后的 html
+
+```typescript
+TiptapShiki.configure({
+  // 传递配置项之后 使用tiptap的 getHTML将会返回高亮后的 html
+  // 注意：如果启用了 getHighlighHTML，返回的 HTML 不能用于setContent 回填，所以请储存getJSON用来编辑，而 html 只用来做前台展示
+  getHighlighHTML: true,
+}),
+```
+
+### 自定义工具栏
+
+```typescript
+// 你可以导入预制的样式文件来使用，也可以自行编写样式
+import "tiptap-extension-shiki/dist/style.css";
+
+TiptapShiki.configure({
+  renderToolbar: ({ language, theme, toolbarDOM, setTheme, setLanguage }) => {
+    // 在这里，您可以按照自己的方式(React/VUE)插入 DOM 到 toolbarDOM 中。
+    // 例如，您可以使用 renderer(VNode,toolbarDOM)
+
+    // 示例用原生 dom 来创建工具栏
+    // Create language selection dropdown
+    const languageSelect = document.createElement("select");
+    languageSelect.style.cssText =
+      "width: 200px; padding: 4px 8px; margin-right: 8px;";
+    languageSelect.innerHTML = `
+            <option value="javascript">JavaScript</option>
+            <option value="typescript">TypeScript</option>
+            <option value="html">HTML</option>
+            <option value="css">CSS</option>
+            <option value="python">Python</option>
+            <option value="json">JSON</option>
+            <option value="c++">C++</option>
+          `;
+
+    // Create theme selection dropdown
+    const themeSelect = document.createElement("select");
+    themeSelect.style.cssText = "width: 200px; padding: 4px 8px;";
+    themeSelect.innerHTML = `
+            <option value="dracula">Dracula</option>
+            <option value="dark-plus">DarkPlus</option>
+          `;
+
+    // Add language change event listener
+    languageSelect.addEventListener("change", (event) => {
+      // 设置选中的语言
+      setLanguage((event.target as HTMLSelectElement).value);
+    });
+
+    // Add theme change event listener
+    themeSelect.addEventListener("change", (event) => {
+      // 设置选中的主题
+      setTheme((event.target as HTMLSelectElement).value);
+    });
+
+    // 在工具栏容器中添加DOM
+    toolbarDOM.appendChild(languageSelect);
+    toolbarDOM.appendChild(themeSelect);
+  },
+});
+```
+
+### 功能特性
+
+- ✨ 支持多种编程语言切换
+- 🎨 支持多种主题切换
+- 🛠️ 可自定义工具栏界面
+- 🚀 实时语法高亮渲染
+- 🔧 基于 Shiki 的高性能语法高亮引擎
+
+### 配置选项
+
+| 选项              | 类型          | 默认值         | 描述                      |
+| ----------------- | ------------- | -------------- | ------------------------- |
+| `defaultTheme`    | `string`      | `'dracula'`    | 默认语法高亮主题 （必需） |
+| `defaultLanguage` | `string`      | `'javascript'` | 默认编程语言 （必需）     |
+| `highlighter`     | `Highlighter` | `undefined`    | Shiki 高亮器实例（必需）  |
+| `getHighlighHTML` | `boolean`     | `false`        | 是否生成静态高亮 HTML     |
+| `renderToolbar`   | `function`    | `undefined`    | 自定义工具栏渲染函数      |
+
+### 自定义样式
+
+你可以通过 CSS 自定义代码块的外观：
+
+```css
+.tiptap-shiki--container {
+  border-radius: 8px;
+  font-family: "Fira Code", monospace;
+}
+
+.tiptap-shiki--toolbar {
+  background: rgba(0, 0, 0, 0.05);
+  border-radius: 6px 6px 0 0;
+}
+```
+
+### 贡献
+这个插件参考了原有的高亮插件
+[extension-code-block-lowlight](https://github.com/ueberdosis/tiptap/tree/main/packages/extension-code-block-lowlight)
+
+### 注意事项
+
+1. 使用前必须创建并配置 Shiki 高亮器实例
+2. 自定义工具栏函数中的 DOM 操作是安全的，编辑器会处理冲突
+3. 确保在使用前安装所有依赖包
+
+### 许可证
+
+MIT License

package/dist/ShikiLightPlugin.d.ts

@@ -0,0 +1,19 @@
+import { Plugin } from "@tiptap/pm/state";
+import type { BundledLanguage, BundledTheme, HighlighterGeneric, SpecialLanguage, StringLiteralUnion, ThemeRegistrationAny } from "shiki";
+/**
+ * 创建Shiki轻量级语法高亮插件
+ * 该插件负责在ProseMirror编辑器中为代码块提供实时的语法高亮显示
+ * 通过ProseMirror的装饰器系统实现高性能的语法高亮渲染
+ *
+ * @param name - 插件名称
+ * @param highlighter - Shiki语法高亮器实例
+ * @param defaultTheme - 默认主题
+ * @param defaultLanguage - 默认编程语言
+ * @returns ProseMirror插件实例
+ */
+export declare function ShikiLightPlugin({ name, highlighter, defaultTheme, defaultLanguage, }: {
+    name: string;
+    highlighter: HighlighterGeneric<BundledLanguage, BundledTheme>;
+    defaultTheme: ThemeRegistrationAny | StringLiteralUnion<string>;
+    defaultLanguage: StringLiteralUnion<SpecialLanguage>;
+}): Plugin<any>;

package/dist/index.cjs.css

@@ -0,0 +1 @@
+.tiptap-shiki--container{border-radius:.4rem;font-size:.875em;pre{max-height:400px;overflow:auto;padding:20px}}.tiptap-shiki--toolbar{align-items:center;display:flex;padding:10px}