@cellgit/markdown-render

v0.1.0

Published

a month ago

A frontend markdown rendering library with syntax highlighting, math support, and iOS system colors adaptation

0High
0Medium
0Low

markdown render renderer highlight syntax-highlighting katex math latex ios android webview react vue browser dark-mode system-colors mobile

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 安装（推荐）

npm install markdown-render
# 或
yarn add markdown-render
# 或
pnpm add markdown-render

从源码构建

git clone <repository-url>
cd markdown-render
npm install
npm run build

使用方法

在 npm 项目中使用

React 示例：

import { renderMarkdown } from 'markdown-render';
import 'markdown-render/styles';

function App() {
  const html = renderMarkdown('# Hello **React**!');
  return <div dangerouslySetInnerHTML={{ __html: html }} />;
}

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：

import { renderMarkdown } from 'markdown-render';
import 'markdown-render/styles';

const html = renderMarkdown('# Hello **World**!');
document.getElementById('app').innerHTML = html;

📚 完整文档：

NPM 使用指南 - 详细的 npm 使用说明
示例代码 - React、Vue、Vanilla JS 完整示例

在 iOS 项目中使用

专为 iOS 打包：

npm run build:ios

这会在 ios-bundle/ 目录生成适用于 iOS 的文件包。详细集成步骤请查看 iOS 集成指南。

快速开始：

运行 npm run build:ios
将 ios-bundle/ 中的文件添加到 Xcode 项目
使用 MarkdownViewController 渲染 Markdown

需要自定义 WebView 模板？请编辑 templates/markdown-render.html，然后重新运行 npm run build 或 npm run build:ios，生成的 dist/markdown-render.html 会自动更新并被后续打包脚本使用。

let markdownVC = MarkdownViewController()
markdownVC.renderMarkdown("# Hello iOS\nThis is **bold** text!")

完整示例代码请参考 ios-example/MarkdownViewController.swift。

在 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 中使用

import { renderMarkdown } from './dist/markdown-render.js';

const html = renderMarkdown('# Hello World');
console.log(html);

添加复制代码功能

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 架构，可以轻松扩展后处理功能：

// src/pipeline/index.js
const pipelines = [
  addCopyButton,    // 添加复制按钮
  handleLinks       // 处理链接
];

export function applyPipeline(html) {
  return pipelines.reduce((currentHtml, processor) => {
    return processor(currentHtml);
  }, html);
}

自定义 Pipeline

你可以添加自己的 pipeline 处理器：

// 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

构建

npm run build

构建产物：dist/markdown-render.js (约 1.3MB)

测试

在浏览器中打开 test.html 查看所有功能演示。

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

致谢

本项目基于以下优秀开源项目：