Merge pull request #5 from BeiyanYunyi/feature_preview

✨ Preview

docs/.vitepress/config.ts

@@ -1,5 +1,6 @@
-import { defineConfig } from 'vitepress';
 import { withPwa } from '@vite-pwa/vitepress';
+import { defineConfig } from 'vitepress';
+import mk from '@traptitech/markdown-it-katex';
 
 export default withPwa(
   defineConfig({
@@ -28,5 +29,25 @@ export default withPwa(
       ],
     },
     pwa: { base: process.env.DOCS_BASE, selfDestroying: true },
+    vite: {
+      optimizeDeps: {
+        include: [
+          'remark-gfm',
+          'remark-parse',
+          'remark-rehype',
+          'rehype-document',
+          'rehype-format',
+          'rehype-stringify',
+          'unified',
+          'remark-math',
+          'rehype-katex',
+        ],
+      },
+    },
+    markdown: {
+      config: (md) => {
+        md.use(mk);
+      },
+    },
   }),
 );

docs/.vitepress/theme/SodesuComment.vue

@@ -18,12 +18,16 @@ import '../../../dist/sodesu.css';
 import { onMounted } from 'vue';
 
 onMounted(async () => {
-  const Sodesu = await import('../../../dist/sodesu.aio.mjs');
+  const [Sodesu, remarkRenderer] = await Promise.all([
+    import('../../../dist/sodesu.aio.mjs'),
+    import('../../../src/utils/remarkRenderer'),
+  ]);
   Sodesu.default.init({
     el: '#sodesu-comment',
     serverURL: 'https://walinejs.comment.lithub.cc',
     dark: 'html.dark',
     commentClassName: 'vp-doc',
+    renderPreview: remarkRenderer.default,
   });
 });
 </script>

docs/.vitepress/theme/index.ts

@@ -1,5 +1,6 @@
 import DefaultTheme from 'vitepress/theme';
 import SodesuLayout from './SodesuLayout.vue';
+import 'katex/dist/katex.min.css';
 
 const theme: typeof DefaultTheme = {
   ...DefaultTheme,

docs/index.md

@@ -19,11 +19,11 @@ features:
     details: 又快又小。使用长得像 JSX 的模板构建。
   - icon: 📦
     title: 使用 UnoCSS
-    details: CSS 体积控制在 7.86kB，如果你的博客系统也用了 UnoCSS，那么 CSS 体积不会简单相加。
+    details: CSS 体积控制在 8.97kB，如果你的博客系统也用了 UnoCSS，那么 CSS 体积不会简单相加。
   - icon: ❤
     title: 兼容 Waline
     details: 可直接重用原版 Waline 前端的配置项，迁移简单。
   - icon: ☁️
     title: 轻量
-    details: 20 kB gzipped 的完整 JS 体积。
+    details: 23 kB gzipped 的完整 JS 体积。
 ---

docs/special-features.md

@@ -18,3 +18,44 @@ Sodesu.init({
 ```
 
 其中的 `commentClassName` 会被应用到每条评论的容器上。
+
+## 自定义 Markdown 渲染器
+
+Sodesu 默认使用 [snarkdown](https://www.npmjs.com/package/@bpmn-io/snarkdown) 渲染 Markdown 预览。作为一个体积只有 1.15kB Gzipped 的 Markdown 渲染器，snarkdown 存在一些缺陷，例如不支持代码高亮。
+
+Sodesu 提供了自定义 Markdown 渲染器的功能，你可以使用任何你喜欢的 Markdown 渲染器，例如 [marked](https://www.npmjs.com/package/marked)、[markdown-it](https://www.npmjs.com/package/markdown-it) 和 [remark](https://www.npmjs.com/package/remark) 等。
+
+你可以通过在 init 时传入自定义参数来自定义 Markdown 渲染器。
+
+```js
+import Sodesu from 'sodesu-comment';
+Sodesu.init({
+  el: '#comment-container',
+  // ...
+  renderPreview: async (text) => myProcessor(text), // 需要返回 Promise
+});
+```
+
+对于使用 `remark` 的情况，项目代码中提供了一个[示例](https://github.com/BeiyanYunyi/sodesu/blob/main/src/utils/remarkRenderer.ts)，你正在阅读的文档页面也[使用了它](https://github.com/BeiyanYunyi/sodesu/blob/main/docs/.vitepress/theme/SodesuComment.vue)。因此，你可以试着在评论框里键入如下内容，并点击“预览”图标：
+
+```markdown
+| 114  | 514 |
+| :--: | :-: |
+| 1919 | 810 |
+
+$$
+\frac{\text d\rho}{\text dt}+\rho\bold\nabla\cdot\vec V=0
+$$
+```
+
+它的渲染结果应该如下所示：
+
+| 114  | 514 |
+| :--: | :-: |
+| 1919 | 810 |
+
+$$
+\frac{\text d\rho}{\text dt}+\rho\bold\nabla\cdot\vec V=0
+$$
+
+从一致性的角度出发，我会推荐 `markdown-it`，这是 waline 后端使用的渲染器。你可以参照它的代码，对渲染器进行配置。

docs/trade-offs.md

@@ -23,12 +23,6 @@ Waline 后端使用 Prism 将 markdown 中的代码块进行高亮处理，而 S
 
 ## 将来可能实现的特性
 
-### Markdown 预览
-
-这涉及 Markdown 的前端渲染。Waline 官方前端使用的方案是 marked。marked 的体积很大，引入它会使 Sodesu 的体积增加 48kB（16kB Gzipped），换句话说，让 Sodesu 的体积翻一倍。
-
-我的博客偏技术型，相对而言，用户的 markdown 熟练度会更高一些，因此 Markdown 预览功能的优先度并不高。尽管如此，我仍然会尝试实现 Markdown 预览——用 [snarkdown](https://github.com/developit/snarkdown) ，或者暴露一个函数，以让用户调用例如自行反代的 [GitHub 现成的接口](https://docs.github.com/en/rest/markdown#render-a-markdown-document)来实现。
-
 ### 表情选择
 
 我认为直接让用户输入 Emoji 会是个更好的选择。尽管如此，引入一个表情选择器的代价并不大，我可以尝试着去做，但优先级并不高。

index.html

@@ -14,6 +14,7 @@
     <div id="root"></div>
     <script type="module">
       import Sodesu from '/src/index.tsx';
+      import remarkRenderer from '/src/utils/remarkRenderer.ts';
       import 'virtual:uno.css';
       Sodesu.init({
         el: '#root',
@@ -24,6 +25,7 @@
         pageview: true,
         comment: true,
         commentClassName: 'prose',
+        renderPreview: remarkRenderer,
       });
     </script>
     <link

package.json

@@ -91,6 +91,7 @@
   "license": "AGPL-3.0-or-later",
   "devDependencies": {
     "@babel/core": "^7.22.5",
+    "@bpmn-io/snarkdown": "^2.2.0",
     "@giphy/js-types": "^4.4.0",
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-commonjs": "^25.0.1",
@@ -100,6 +101,7 @@
     "@rollup/plugin-typescript": "^11.1.1",
     "@solid-primitives/date": "^2.0.14",
     "@solid-primitives/storage": "^1.3.11",
+    "@traptitech/markdown-it-katex": "^3.6.0",
     "@types/babel__core": "^7.20.1",
     "@types/node": "^20.3.1",
     "@typescript-eslint/eslint-plugin": "^5.59.11",
@@ -117,12 +119,22 @@
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-prettier": "^4.0.0",
     "eslint-plugin-solid": "^0.12.1",
+    "katex": "^0.16.8",
     "prettier": "^2.8.8",
+    "rehype-document": "^6.1.0",
+    "rehype-format": "^4.0.1",
+    "rehype-katex": "^6.0.3",
+    "rehype-stringify": "^9.0.3",
+    "remark-gfm": "^3.0.1",
+    "remark-math": "^5.1.1",
+    "remark-parse": "^10.0.2",
+    "remark-rehype": "^10.1.0",
     "rimraf": "^5.0.1",
     "rollup": "^3.25.1",
     "rollup-plugin-dts": "^5.3.0",
     "rollup-plugin-summary": "^2.0.0",
     "typescript": "^5.1.3",
+    "unified": "^10.1.2",
     "unocss": "^0.53.1",
     "vite": "^4.3.9",
     "vite-plugin-pwa": "^0.16.4",