hexo-markdown-mermaid 0.0.1

package/README.md

@@ -0,0 +1,95 @@
+# hexo-markdown-mermaid
+
+A Hexo plugin for rendering Mermaid diagrams in your posts.
+
+[简体中文](./README.zh-CN.md)
+
+## Installation
+
+```bash
+npm install hexo-markdown-mermaid
+```
+
+## Quick Start
+
+Add mermaid code blocks in your posts:
+
+````markdown
+```mermaid
+graph TD
+A-->B
+A-->C
+B-->D
+C-->D
+```
+````
+
+## Configuration
+
+### With Syntax Highlighter (Recommended)
+
+Only highlight.js is supported. exclude mermaid so Mermaid.js can render it:
+
+```yaml
+highlight:
+  enable: true
+  exclude_languages:
+    - mermaid
+```
+
+:::warning
+PrismJS is not supported as it does not have `exclude_languages` option.
+:::
+
+### Mermaid Options
+
+```yaml
+mermaid:
+  version: 11
+  startOnLoad: true
+  theme: default
+  # Other mermaid config options...
+```
+
+#### Available Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `version` | Mermaid version | 11 |
+| `startOnLoad` | Auto-render on page load | true |
+| Other options | See [Mermaid Config](https://mermaid.js.org/config/schema-docs/config.html) | - |
+
+## License
+
+MIT
+
+---
+
+## Technical Details
+
+### Why render in browser instead of build-time?
+
+Mermaid CLI (mermaid-cli) can pre-render diagrams at build time, but it has heavy dependencies (requires Puppeteer or similar), making it unsuitable for most Hexo setups.
+
+This plugin chooses browser-side rendering for simplicity and broad compatibility.
+
+### Why exclude mermaid from syntax highlighter?
+
+When using highlight.js with Hexo's `highlight.enable: true`, code blocks are pre-rendered to HTML with each line wrapped in `<span class="line">`:
+
+```html
+<pre><span class="line">graph TD</span>
+<span class="line">A--&gt;B</span></pre>
+```
+
+Mermaid.js searches for elements with class `.mermaid`. After excluding mermaid, code blocks will be rendered as:
+
+```html
+<pre><code class="highlight mermaid">graph TD\nA--&gt;B</code></pre>
+```
+
+This allows Mermaid.js to find and render the diagrams correctly.
+
+### Mermaid Selector
+
+This plugin uses Mermaid's default query selector `.mermaid`. See [Mermaid RunOptions](https://mermaid.js.org/config/setup/mermaid/interfaces/RunOptions.html#queryselector).

package/README.zh-CN.md

@@ -0,0 +1,93 @@
+# hexo-markdown-mermaid
+
+Hexo 插件，用于在文章中渲染 Mermaid 图表。
+
+## 安装
+
+```bash
+npm install hexo-markdown-mermaid
+```
+
+## 快速开始
+
+在文章中添加 mermaid 代码块：
+
+````markdown
+```mermaid
+graph TD
+A-->B
+A-->C
+B-->D
+C-->D
+```
+````
+
+## 配置
+
+### 使用语法高亮器（推荐）
+
+仅支持 highlight.js。需排除 mermaid 以便 Mermaid.js 渲染：
+
+```yaml
+highlight:
+  enable: true
+  exclude_languages:
+    - mermaid
+```
+
+:::warning
+PrismJS 不支持，因为没有 `exclude_languages` 选项。
+:::
+
+### Mermaid 选项
+
+```yaml
+mermaid:
+  version: 11
+  startOnLoad: true
+  theme: default
+  # 其他 mermaid 配置选项...
+```
+
+#### 可用选项
+
+| 选项 | 描述 | 默认值 |
+|------|------|--------|
+| `version` | Mermaid 版本 | 11 |
+| `startOnLoad` | 页面加载时自动渲染 | true |
+| 其他选项 | 参阅 [Mermaid 配置](https://mermaid.js.org/config/schema-docs/config.html) | - |
+
+## 许可
+
+MIT
+
+---
+
+## 技术细节
+
+### 为什么在浏览器端渲染而非构建时？
+
+Mermaid CLI 可以在构建时预渲染图表，但它依赖较重（需要 Puppeteer 或类似工具），不适合大多数 Hexo 环境。
+
+本插件选择浏览器端渲染，以保持简洁和广泛兼容性。
+
+### 为什么要排除 mermaid？
+
+使用 highlight.js 且 Hexo 配置 `highlight.enable: true` 时，代码块会被预渲染为 HTML，每行被包装在 `<span class="line">` 中：
+
+```html
+<pre><span class="line">graph TD</span>
+<span class="line">A--&gt;B</span></pre>
+```
+
+Mermaid.js 查找 class 为 `.mermaid` 的元素。排除后，代码块会渲染为：
+
+```html
+<pre><code class="highlight mermaid">graph TD\nA--&gt;B</code></pre>
+```
+
+这样 Mermaid.js 就能正确找到并渲染图表。
+
+### Mermaid 选择器
+
+本插件使用 Mermaid 默认的查询选择器 `.mermaid`。参阅 [Mermaid RunOptions](https://mermaid.js.org/config/setup/mermaid/interfaces/RunOptions.html#queryselector)。

package/index.js

@@ -0,0 +1,14 @@
+const mermaidVersion = hexo.config.mermaid?.version || '11';
+const { version: _version, ...userConfig } = hexo.config.mermaid || {};
+const mermaidConfig = Object.assign({
+  startOnLoad: true
+}, userConfig);
+
+hexo.extend.injector.register('body_end', `
+<script src="https://cdn.jsdelivr.net/npm/mermaid@${mermaidVersion}/dist/mermaid.min.js"></script>
+<script>
+  document.addEventListener('DOMContentLoaded', function() {
+    mermaid.initialize(${JSON.stringify(mermaidConfig)});
+  });
+</script>
+`, 'default');

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "hexo-markdown-mermaid",
+  "version": "0.0.1",
+  "description": "A Hexo plugin for rendering Mermaid diagrams",
+  "main": "index.js",
+  "keywords": ["hexo", "mermaid", "plugin"],
+  "license": "MIT",
+  "devDependencies": {
+    "chai": "^4.4.1",
+    "mocha": "^10.4.0"
+  },
+  "scripts": {
+    "test": "mocha"
+  }
+}

package/test/index.test.js

@@ -0,0 +1,70 @@
+'use strict';
+
+require('chai').should();
+
+const mockHexo = (config = {}) => {
+  const registeredInjectors = [];
+
+  const mock = {
+    extend: {},
+    config: Object.assign({}, config)
+  };
+  mock.extend.injector = {
+    register: function(position, content, priority) {
+      registeredInjectors.push({ position, content, priority });
+    }
+  };
+  mock._registeredInjectors = registeredInjectors;
+  return mock;
+};
+
+function loadPlugin(hexoMock) {
+  global.hexo = hexoMock;
+  delete require.cache[require.resolve('../index.js')];
+  require('../index.js');
+}
+
+describe('hexo-mermaid', function() {
+  this.timeout(10000);
+
+  describe('injector', function() {
+    it('should register body_end injector with mermaid script', function() {
+      const hexo = mockHexo({});
+      loadPlugin(hexo);
+      const injectors = hexo._registeredInjectors;
+      const mermaidInjector = injectors.find(i => i.position === 'body_end' && i.content.includes('mermaid'));
+      mermaidInjector.should.be.an('object');
+      mermaidInjector.priority.should.equal('default');
+    });
+
+    it('should use default config when no mermaid config', function() {
+      const hexo = mockHexo({});
+      loadPlugin(hexo);
+      const injector = hexo._registeredInjectors[0];
+      injector.content.should.include('"startOnLoad":true');
+    });
+
+    it('should merge user config with default config', function() {
+      const hexo = mockHexo({ mermaid: { theme: 'forest', fontFamily: 'Arial' } });
+      loadPlugin(hexo);
+      const injector = hexo._registeredInjectors[0];
+      injector.content.should.include('"theme":"forest"');
+      injector.content.should.include('"fontFamily":"Arial"');
+      injector.content.should.include('"startOnLoad":true');
+    });
+
+    it('should use default version 11 when no version config', function() {
+      const hexo = mockHexo({});
+      loadPlugin(hexo);
+      const injector = hexo._registeredInjectors[0];
+      injector.content.should.include('mermaid@11/dist/mermaid.min.js');
+    });
+
+    it('should use custom version when specified', function() {
+      const hexo = mockHexo({ mermaid: { version: '10' } });
+      loadPlugin(hexo);
+      const injector = hexo._registeredInjectors[0];
+      injector.content.should.include('mermaid@10/dist/mermaid.min.js');
+    });
+  });
+});