feat: 创建 VitePress 文档与 mjml 邮件模板编译流程

docs 目录包含一个 VitePress 构建的静态文档站点。 mjml 目录包含 HTML 邮件模板。这些模板将被编译为 Jinja2 模板，然后由 NyaHome 动态渲染后发送。
2026-05-24 13:55:56 +08:00
parent c30d65f9ae
commit f06de85257
10 changed files with 3777 additions and 0 deletions
@@ -0,0 +1,35 @@
+import {defineConfig} from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "NyaHome",
+  description: "自托管 AI 创作聊天室平台",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      {text: '主页', link: '/'},
+      {text: '使用', link: '/use/start'}
+    ],
+
+    sidebar: [
+      {
+        text: '使用',
+        items: [
+          {text: '开始', link: '/use/start'},
+          {text: '默认行为', link: '/use/default-action'},
+          {text: '用户系统', link: '/use/user-system'},
+        ]
+      },
+      {
+        text: '开发',
+        items: [
+          {text: '后端响应', link: '/dev/backend-response'},
+        ]
+      },
+    ],
+
+    socialLinks: [
+      {icon: 'github', link: 'https://github.com/vuejs/vitepress'}
+    ]
+  }
+})
@@ -0,0 +1,4 @@
+:root {
+    --vp-c-brand-1: #64ffc4;
+    --vp-c-brand-2: #9354ff;
+}
@@ -0,0 +1,5 @@
+import DefaultTheme from 'vitepress/theme'
+// @ts-ignore
+import './custom.css'
+
+export default DefaultTheme
@@ -0,0 +1,25 @@
+# 邮件模板
+
+NyaHome 希望发送 HTML 邮件，但是用于邮件的 HTML 在 2026 年依然是重灾区。因此，NyaHome 决定采用 mjml 配合 Jinja2 制作并渲染邮件模板。
+
+## 有关工作流程
+
+项目根目录下的 `mjml` 内是 mjml 源文件。这是一种类 xaml 格式的文件，采用独特的语法像编写 HTML 一样编写用于邮件的……也是
+HTML。
+
+通过以下命令，这些 mjml 源文件将会被编译为 j2 源文件，也就是 Jinja2 的模板文件。
+
+```bash
+pnpm mjml mjml/filename.mjml -o public/templates/filename.j2
+```
+
+Jinja2 在 NyaHome 进程中读取模板，渲染变量，然后由 aiosmptplib 发送渲染好的 HTML 邮件。
+
+## 在 PyCharm 中预览 mjml 源文件
+
+使用 **MJML Support** 插件以支持 mjml 源文件的语法高亮、智能补全和实时预览。
+
+:::warning
+MJML Support 插件不支持 JetBrains 远程开发。在远程开发（包括使用 Gateway 进行 WSL 开发）中，IDE client 无法对 mjml
+源文件进行实时预览。
+:::
@@ -0,0 +1,25 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "NyaHome"
+  text: "自托管 AI 创作聊天室平台"
+  tagline: 本地创作 | 在线酒馆
+  actions:
+    - theme: brand
+      text: 开始部署
+      link: /use/start
+    - theme: alt
+      text: 开发
+      link: /dev/start
+
+features:
+  - title: Feature A
+    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: Feature B
+    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: Feature C
+    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+---
+
@@ -0,0 +1,74 @@
+<mjml>
+  <mj-head>
+    <mj-title>
+      {{ site_name }} 验证邮件
+    </mj-title>
+    <mj-preview>
+      包含 5 分钟有效的验证码，由 NyaHome 系统自动发送。
+    </mj-preview>
+    <mj-style>
+      @font-face {
+        font-family: 'Maple Mono CN';
+        src: url('https://assets-cdn.mangofanfan.cn/maple-mono-cn/MapleMono-CN-Medium.woff2') format('woff2'),
+        url("https://assets-cdn.mangofanfan.cn/maple-mono-cn/MapleMono-CN-Medium.ttf") format("truetype");
+        font-weight: normal;
+        font-style: normal;
+        font-display: swap;
+      }
+    </mj-style>
+    <mj-attributes>
+      <mj-all font-family='Maple Mono CN'/>
+    </mj-attributes>
+  </mj-head>
+
+  <mj-body>
+    <mj-section background-color="#f0ffff">
+      <mj-column>
+        <mj-text>
+          {{ site_name }} 自动发送的验证邮件。
+        </mj-text>
+        <mj-text>
+          请不要将您的验证码发给他人。验证码的有效期为 5 分钟。
+        </mj-text>
+      </mj-column>
+    </mj-section>
+
+    <mj-section background-color="#faebd7">
+      <mj-column>
+        <mj-text>
+          {{ email_reason }}
+        </mj-text>
+        <mj-text>
+          如果这不是您本人的请求，请忽略此邮件。您的账户没有风险。
+        </mj-text>
+        <mj-divider/>
+        <mj-text>
+          您的验证码为
+        </mj-text>
+        <mj-text font-size="30px" align="center">
+          {{ otp_number }}
+        </mj-text>
+        <mj-text>
+          请仅在站点 {{ site_name }} 上使用此验证码。
+        </mj-text>
+        <mj-text>
+          站点地址为 {{ site_url }} 。
+        </mj-text>
+      </mj-column>
+    </mj-section>
+
+    <mj-section background-color="#D0FFED">
+      <mj-column>
+        <mj-text>
+          {{ site_name }} - 由 NyaHome 驱动
+        </mj-text>
+        <mj-text>
+          本自动邮件发送于服务器时间 {{ sent_time }}
+        </mj-text>
+        <mj-text>
+          由于这并非定时邮件，因此无法退订喵~
+        </mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>
@@ -0,0 +1,49 @@
+<mjml>
+  <mj-head>
+    <mj-title>
+      {{ site_name }} 测试邮件
+    </mj-title>
+    <mj-preview>
+      由管理员手动发送的测试邮件。
+    </mj-preview>
+    <mj-style>
+      @font-face {
+        font-family: 'Maple Mono CN';
+        src: url('https://assets-cdn.mangofanfan.cn/maple-mono-cn/MapleMono-CN-Medium.woff2') format('woff2'),
+        url("https://assets-cdn.mangofanfan.cn/maple-mono-cn/MapleMono-CN-Medium.ttf") format("truetype");
+        font-weight: normal;
+        font-style: normal;
+        font-display: swap;
+      }
+    </mj-style>
+    <mj-attributes>
+      <mj-all font-family='Maple Mono CN'/>
+    </mj-attributes>
+  </mj-head>
+
+  <mj-body>
+    <mj-section background-color="#faebd7">
+      <mj-column>
+        <mj-text>这是一封测试邮件。</mj-text>
+        <mj-text>
+          {{ site_name }} 的管理员选择向此邮箱发送了一封测试邮件。此邮件不含有任何有效内容。
+        </mj-text>
+        <mj-text>但是邮件内容写太少了有一种负罪感，所以还是多叽里咕噜地写几句话吧。</mj-text>
+      </mj-column>
+    </mj-section>
+
+    <mj-section background-color="#D0FFED">
+      <mj-column>
+        <mj-text>
+          {{ site_name }} - 由 NyaHome 驱动
+        </mj-text>
+        <mj-text>
+          本自动邮件发送于服务器时间 {{ sent_time }}
+        </mj-text>
+        <mj-text>
+          由于这并非定时邮件，因此无法退订喵~
+        </mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>
@@ -0,0 +1,11 @@
+{
+  "devDependencies": {
+    "mjml": "^5.2.2",
+    "vitepress": "2.0.0-alpha.17"
+  },
+  "scripts": {
+    "dev": "vitepress dev docs",
+    "build": "vitepress build docs",
+    "preview": "vitepress preview docs"
+  }
+}