@cellgit/markdown-render 0.1.0

package/QUICK_START_iOS.md

@@ -0,0 +1,219 @@
+# iOS 快速开始指南
+
+快速 5 步集成 markdown-render 到你的 iOS 项目。
+
+## 第 1 步：打包文件
+
+```bash
+cd markdown-render
+npm install
+npm run build:ios
+```
+
+✅ 完成后会在 `ios-bundle/` 目录生成所有需要的文件
+（模板源文件位于 `templates/markdown-render.html`，如需修改请编辑后重新运行上述命令。）
+
+## 第 2 步：添加文件到 Xcode
+
+1. 打开你的 Xcode 项目
+2. 在项目导航器中右键点击 → New Group
+3. 命名为 `markdown-render-bundle`
+4. 将 `ios-bundle/` 目录下的**所有文件**拖入该分组
+   - ✅ markdown-render.html
+   - ✅ markdown-render.js
+   - ✅ markdown-render.css
+   - ✅ fonts/ 目录
+5. **重要**：在弹出的对话框中：
+   - ✅ 勾选 "Copy items if needed"
+   - ✅ 选择 "Create folder references" （蓝色文件夹图标）
+   - ✅ 确保添加到正确的 Target
+
+## 第 3 步：添加 Swift 代码
+
+将 `ios-example/MarkdownViewController.swift` 复制到你的项目中。
+
+或者在终端运行：
+```bash
+cp ios-example/MarkdownViewController.swift /path/to/your/xcode/project/
+```
+
+## 第 4 步：使用
+
+### UIKit
+
+```swift
+import UIKit
+
+class MyViewController: UIViewController {
+    private let markdownVC = MarkdownViewController()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+
+        // 添加子视图控制器
+        addChild(markdownVC)
+        view.addSubview(markdownVC.view)
+        markdownVC.view.frame = view.bounds
+        markdownVC.didMove(toParent: self)
+
+        // 渲染 Markdown
+        let markdown = """
+        # Hello iOS! 👋
+
+        This is **bold** and this is *italic*.
+
+        ```swift
+        print("Hello, World!")
+        ```
+
+        Math: $E = mc^2$
+
+        - [x] Task completed
+        - [ ] Task pending
+        """
+
+        markdownVC.renderMarkdown(markdown)
+    }
+}
+```
+
+### SwiftUI
+
+```swift
+import SwiftUI
+
+struct MarkdownView: UIViewControllerRepresentable {
+    let markdown: String
+
+    func makeUIViewController(context: Context) -> MarkdownViewController {
+        MarkdownViewController()
+    }
+
+    func updateUIViewController(_ uiViewController: MarkdownViewController, context: Context) {
+        uiViewController.renderMarkdown(markdown)
+    }
+}
+
+struct ContentView: View {
+    var body: some View {
+        MarkdownView(markdown: "# Hello SwiftUI\nThis is **bold**!")
+            .edgesIgnoringSafeArea(.all)
+    }
+}
+```
+
+## 第 5 步：运行测试
+
+1. 在模拟器或设备上运行应用
+2. 如果看不到内容，检查：
+   - [ ] 文件是否正确添加到 Target
+   - [ ] 是否使用了 "Create folder references"
+   - [ ] 查看 Xcode 控制台是否有错误
+
+## 调试技巧
+
+### 文件路径问题
+
+如果提示找不到 HTML 文件，检查文件路径：
+
+```swift
+// 在 MarkdownViewController 的 loadHTMLFile() 方法中添加调试输出
+guard let htmlPath = Bundle.main.path(forResource: "markdown-render", ofType: "html", inDirectory: "markdown-render-bundle") else {
+    print("❌ HTML file not found!")
+    print("Bundle path: \(Bundle.main.bundlePath)")
+    return
+}
+print("✅ HTML path: \(htmlPath)")
+```
+
+### Safari Web Inspector
+
+1. 打开 Safari → 偏好设置 → 高级
+2. 勾选 "在菜单栏中显示开发菜单"
+3. 在设备/模拟器运行应用
+4. Safari → 开发 → [你的设备] → [WebView]
+5. 查看 JavaScript 控制台错误
+
+### 常见问题
+
+**问题：白屏无内容**
+- 检查是否使用了 "Create folder references" 而不是 "Create groups"
+- 确认 fonts 目录包含所有字体文件
+
+**问题：数学公式不显示**
+- 确认 fonts 目录正确添加
+- 检查 CSS 文件是否加载
+
+**问题：代码高亮不工作**
+- 确认 markdown-render.js 文件完整
+- 查看浏览器控制台是否有 JavaScript 错误
+
+## 进阶功能
+
+### 动态调整高度
+
+```swift
+markdownVC.renderMarkdown(markdown)
+
+// 渲染完成后获取高度
+DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+    markdownVC.getContentHeight { height in
+        print("Content height: \(height)")
+        // 更新约束或 frame
+    }
+}
+```
+
+### 清空内容
+
+```swift
+markdownVC.clearContent()
+```
+
+### 监听渲染完成
+
+在 `MarkdownViewController` 中已经实现了 `renderComplete` 消息处理，你可以修改代码添加回调：
+
+```swift
+var onRenderComplete: ((Bool) -> Void)?
+
+extension MarkdownViewController: WKScriptMessageHandler {
+    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+        if message.name == "renderComplete" {
+            if let body = message.body as? [String: Any],
+               let success = body["success"] as? Bool {
+                onRenderComplete?(success)
+            }
+        }
+    }
+}
+```
+
+## 完整文档
+
+- 详细集成指南：[ios-example/README.md](ios-example/README.md)
+- Swift 源码参考：[ios-example/MarkdownViewController.swift](ios-example/MarkdownViewController.swift)
+- 功能演示：在浏览器打开 `test.html`
+
+## 更新库
+
+当 markdown-render 有更新时：
+
+```bash
+git pull
+npm install
+npm run build:ios
+```
+
+然后在 Xcode 中替换 `markdown-render-bundle` 目录下的文件。
+
+## 技术支持
+
+有问题？
+- 查看 [完整文档](README.md)
+- 参考 [iOS 集成指南](ios-example/README.md)
+- 查看 [test.html](test.html) 浏览器演示
+
+---
+
+🎉 完成！现在你的 iOS 应用已经支持完整的 Markdown 渲染功能了！

package/README.md

@@ -0,0 +1,343 @@
+# markdown-render
+
+一个功能完整的前端 Markdown 渲染库，基于 markdown-it，支持语法高亮、数学公式、任务列表、Emoji 等特性。完美兼容 WebView、Web、React Native 和 Electron。
+
+## 特性
+
+✅ **基于 markdown-it** - 使用业界标准的 markdown-it 解析器
+✅ **语法高亮** - 内置 highlight.js，支持 180+ 编程语言
+✅ **数学公式** - KaTeX 集成，支持行内和块级数学公式
+✅ **任务列表** - 支持 `- [x]` 和 `- [ ]` 语法
+✅ **嵌套列表** - 支持多层嵌套列表（有序/无序）
+✅ **Emoji** - 支持 emoji shortcode，如 `:smile:` :smile:
+✅ **表格** - 完整的 markdown 表格支持
+✅ **代码块增强** - 带语言标签和复制按钮的代码块
+✅ **主题支持** - 内置明暗主题自动切换
+✅ **单文件输出** - 所有依赖打包在一个 JS 文件中
+✅ **Pipeline 架构** - 可扩展的后处理机制
+
+## 安装
+
+### 从 npm 安装（推荐）
+
+```bash
+npm install markdown-render
+# 或
+yarn add markdown-render
+# 或
+pnpm add markdown-render
+```
+
+### 从源码构建
+
+```bash
+git clone <repository-url>
+cd markdown-render
+npm install
+npm run build
+```
+
+## 使用方法
+
+### 在 npm 项目中使用
+
+**React 示例：**
+```jsx
+import { renderMarkdown } from 'markdown-render';
+import 'markdown-render/styles';
+
+function App() {
+  const html = renderMarkdown('# Hello **React**!');
+  return <div dangerouslySetInnerHTML={{ __html: html }} />;
+}
+```
+
+**Vue 示例：**
+```vue
+<template>
+  <div v-html="html"></div>
+</template>
+
+<script setup>
+import { renderMarkdown } from 'markdown-render';
+import 'markdown-render/styles';
+
+const html = renderMarkdown('# Hello **Vue**!');
+</script>
+```
+
+**Vanilla JS：**
+```javascript
+import { renderMarkdown } from 'markdown-render';
+import 'markdown-render/styles';
+
+const html = renderMarkdown('# Hello **World**!');
+document.getElementById('app').innerHTML = html;
+```
+
+📚 **完整文档：**
+- [NPM 使用指南](NPM_USAGE.md) - 详细的 npm 使用说明
+- [示例代码](examples/) - React、Vue、Vanilla JS 完整示例
+
+### 在 iOS 项目中使用
+
+专为 iOS 打包：
+
+```bash
+npm run build:ios
+```
+
+这会在 `ios-bundle/` 目录生成适用于 iOS 的文件包。详细集成步骤请查看 [iOS 集成指南](ios-example/README.md)。
+
+快速开始：
+1. 运行 `npm run build:ios`
+2. 将 `ios-bundle/` 中的文件添加到 Xcode 项目
+3. 使用 `MarkdownViewController` 渲染 Markdown
+
+> 需要自定义 WebView 模板？请编辑 `templates/markdown-render.html`，然后重新运行 `npm run build` 或 `npm run build:ios`，生成的 `dist/markdown-render.html` 会自动更新并被后续打包脚本使用。
+
+```swift
+let markdownVC = MarkdownViewController()
+markdownVC.renderMarkdown("# Hello iOS\nThis is **bold** text!")
+```
+
+完整示例代码请参考 `ios-example/MarkdownViewController.swift`。
+
+### 在 HTML 中使用
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Markdown Render Example</title>
+</head>
+<body>
+  <div id="output"></div>
+
+  <script src="dist/markdown-render.js"></script>
+  <script>
+    const markdown = `
+# Hello World
+
+This is **bold** and this is *italic*.
+
+\`\`\`javascript
+console.log("Hello, World!");
+\`\`\`
+
+Math: $E = mc^2$
+`;
+
+    const html = MarkdownRender.renderMarkdown(markdown);
+    document.getElementById('output').innerHTML = html;
+  </script>
+</body>
+</html>
+```
+
+### 在 ES Module 中使用
+
+```javascript
+import { renderMarkdown } from './dist/markdown-render.js';
+
+const html = renderMarkdown('# Hello World');
+console.log(html);
+```
+
+### 添加复制代码功能
+
+```javascript
+document.addEventListener('click', function(e) {
+  if (e.target.classList.contains('code-copy-button') ||
+      e.target.closest('.code-copy-button')) {
+    const button = e.target.classList.contains('code-copy-button')
+      ? e.target
+      : e.target.closest('.code-copy-button');
+
+    const wrapper = button.closest('.code-block-wrapper');
+    if (!wrapper) return;
+
+    const codeNode = wrapper.querySelector('code');
+    const codeText = codeNode ? codeNode.textContent : '';
+
+    navigator.clipboard.writeText(codeText).then(() => {
+      const copyTextSpan = button.querySelector('.copy-text');
+      copyTextSpan.textContent = 'Copied!';
+      setTimeout(() => {
+        copyTextSpan.textContent = 'Copy code';
+      }, 2000);
+    });
+  }
+});
+```
+
+## 功能示例
+
+### 代码块
+
+\`\`\`javascript
+function hello() {
+  console.log("Hello, World!");
+}
+\`\`\`
+
+### 数学公式
+
+行内数学：$E = mc^2$
+
+块级数学：
+
+$$
+\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}
+$$
+
+### 任务列表
+
+- [x] 已完成的任务
+- [ ] 未完成的任务
+
+### 嵌套列表
+
+- 第一层
+  - 第二层
+    - 第三层
+
+### 表格
+
+| 列1 | 列2 | 列3 |
+|-----|-----|-----|
+| A   | B   | C   |
+| 1   | 2   | 3   |
+
+### Emoji
+
+支持 emoji shortcode：:smile: :heart: :rocket:
+
+## 项目结构
+
+```
+markdown-render/
+├── src/
+│   ├── index.js              # 主入口
+│   ├── markdown.js           # markdown-it 配置
+│   ├── highlight.js          # 代码高亮
+│   ├── math.js               # 数学公式渲染
+│   ├── utils.js              # 工具函数
+│   ├── styles.css            # 样式表
+│   └── pipeline/             # Pipeline 后处理
+│       ├── index.js          # Pipeline 编排
+│       ├── copy-button.js    # 复制按钮
+│       └── link-handler.js   # 链接处理
+├── dist/
+│   └── markdown-render.js    # 构建产物
+├── package.json
+├── rollup.config.js
+└── test.html                 # 测试页面
+```
+
+## Pipeline 机制
+
+本库采用 Pipeline 架构，可以轻松扩展后处理功能：
+
+```javascript
+// src/pipeline/index.js
+const pipelines = [
+  addCopyButton,    // 添加复制按钮
+  handleLinks       // 处理链接
+];
+
+export function applyPipeline(html) {
+  return pipelines.reduce((currentHtml, processor) => {
+    return processor(currentHtml);
+  }, html);
+}
+```
+
+## 自定义 Pipeline
+
+你可以添加自己的 pipeline 处理器：
+
+```javascript
+// src/pipeline/my-processor.js
+export function myProcessor(html) {
+  // 处理 html
+  return html;
+}
+
+// 在 src/pipeline/index.js 中添加
+import { myProcessor } from './my-processor.js';
+
+const pipelines = [
+  addCopyButton,
+  handleLinks,
+  myProcessor  // 添加你的处理器
+];
+```
+
+## 版本依赖
+
+- **markdown-it**: ^14.1.0
+- **highlight.js**: ^11.9.0 (匹配 GPTDemo)
+- **katex**: ^0.16.9 (匹配 GPTDemo)
+- **markdown-it-task-lists**: ^2.1.1
+- **markdown-it-emoji**: ^3.0.0
+
+## 构建
+
+```bash
+npm run build
+```
+
+构建产物：`dist/markdown-render.js` (约 1.3MB)
+
+## 测试
+
+在浏览器中打开 `test.html` 查看所有功能演示。
+
+## CSS 变量
+
+可通过 CSS 变量自定义主题：
+
+```css
+:root {
+  --chat-text-color: #1C1C1E;
+  --chat-link-color: #0A5EFF;
+  --chat-background: #FFFFFF;
+  --chat-code-bg: var(--chat-background);
+  --chat-inline-code-bg: rgba(175, 184, 193, 0.2);
+  --chat-table-border: #D1D5DB;
+  --chat-copy-button-bg: rgba(0, 0, 0, 0.65);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --chat-text-color: #ECECEC;
+    --chat-link-color: #0A84FF;
+    --chat-background: #1C1C1E;
+    /* ... */
+  }
+}
+```
+
+## 浏览器兼容性
+
+- Chrome/Edge: ✅
+- Safari: ✅
+- Firefox: ✅
+- iOS Safari: ✅
+- Android Chrome: ✅
+
+## License
+
+MIT
+
+## 致谢
+
+本项目基于以下优秀开源项目：
+
+- [markdown-it](https://github.com/markdown-it/markdown-it)
+- [highlight.js](https://highlightjs.org/)
+- [KaTeX](https://katex.org/)
+- [markdown-it-task-lists](https://github.com/revin/markdown-it-task-lists)
+- [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji)