docs(usage): usage guide documentaion (#8)

wibus-wee · wuhang2003 · web-flow · commit e0d27f27c350 · 2023-07-18T16:24:14.000+08:00
Co-authored-by: 浮心物语 &lt;108316419+wuhang2003@users.noreply.github.com&gt;
diff --git a/components/Icons/Bitcoin.tsx b/components/Icons/Bitcoin.tsx
@@ -0,0 +1,7 @@
+import { SVGProps } from "react";
+
+export function UilBitcoin(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1.5em" height="1.5em" viewBox="0 0 24 24" {...props}><path fill="currentColor" d="m11.136 12.117l-.596 2.415c.736.185 3.004.921 3.34-.441c.35-1.421-2.009-1.789-2.744-1.974Zm.813-3.297l-.54 2.191c.612.154 2.5.784 2.806-.455c.318-1.293-1.654-1.581-2.266-1.736ZM12 2a10 10 0 1 0 10 10A10 10 0 0 0 12 2Zm4.358 8.575a1.743 1.743 0 0 1-1.385 1.611a1.933 1.933 0 0 1 .997 2.661c-.586 1.692-1.977 1.835-3.827 1.481l-.449 1.82l-1.085-.274l.443-1.795a35.27 35.27 0 0 1-.864-.227l-.445 1.804l-1.084-.273l.45-1.824c-.254-.065-.511-.135-.774-.201l-1.412-.356l.539-1.256s.8.215.788.199a.394.394 0 0 0 .498-.26l1.217-4.939a.583.583 0 0 0-.505-.638c.016-.011-.789-.198-.789-.198l.29-1.172l1.495.378l-.001.006c.225.056.457.11.693.164l.444-1.802l1.085.274l-.436 1.766c.291.068.584.135.87.207l.432-1.755l1.085.274l-.445 1.802c1.37.477 2.372 1.193 2.175 2.523Z"></path></svg>
+  )
+}
diff --git a/components/Icons/CloudCheck.tsx b/components/Icons/CloudCheck.tsx
@@ -0,0 +1,7 @@
+import { SVGProps } from "react";
+
+export function UilCloudCheck(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1.5em" height="1.5em" viewBox="0 0 24 24" {...props}><path fill="currentColor" d="M14.29 14.19L11 17.48l-1.29-1.29a1 1 0 0 0-1.42 0a1 1 0 0 0 0 1.41l2 2a1 1 0 0 0 1.42 0l4-4a1 1 0 0 0 0-1.41a1 1 0 0 0-1.42 0Zm4.13-5.87a7 7 0 0 0-13.36 1.9a4 4 0 0 0-.38 7.65A1 1 0 1 0 5.32 16A2 2 0 0 1 4 14.1a2 2 0 0 1 2-2a1 1 0 0 0 1-1a5 5 0 0 1 9.73-1.6a1 1 0 0 0 .78.66a3 3 0 0 1 .24 5.84a1 1 0 0 0 .25 2h.25a5 5 0 0 0 .17-9.62Z"></path></svg>
+  )
+}
diff --git a/components/Icons/CloudDatabaseTree.tsx b/components/Icons/CloudDatabaseTree.tsx
@@ -0,0 +1,7 @@
+import { SVGProps } from "react";
+
+export function UilCloudDatabaseTree(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1.5em" height="1.5em" viewBox="0 0 24 24" {...props}><path fill="currentColor" d="M22.5 14.5a2 2 0 0 0-2-2h-6a2 2 0 0 0-2 2h-3v-3h2.33A3.66 3.66 0 0 0 13 4.37a5 5 0 0 0-9.43 1.28a3 3 0 0 0 .93 5.85h3v8a1 1 0 0 0 1 1h4a2 2 0 0 0 2 2h6a2 2 0 0 0 2-2v-2a2 2 0 0 0-.28-1a2 2 0 0 0 .28-1Zm-18-5a1 1 0 0 1 0-2a1 1 0 0 0 1-1a3 3 0 0 1 5.84-1a1 1 0 0 0 .78.66a1.65 1.65 0 0 1 1.38 1.67a1.67 1.67 0 0 1-1.67 1.67Zm8 9h-3v-2h3a2 2 0 0 0 .28 1a2 2 0 0 0-.28 1Zm2 2v-2h6v2Zm0-4v-2h6v2Z"></path></svg>
+  )
+}
diff --git a/components/Icons/DesktopCloudAlt.tsx b/components/Icons/DesktopCloudAlt.tsx
@@ -0,0 +1,7 @@
+import { SVGProps } from "react";
+
+export function UilDesktopCloudAlt(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1.5em" height="1.5em" viewBox="0 0 24 24" {...props}><path fill="currentColor" d="M4.5 10H10a3 3 0 0 0 1.07-5.8a4 4 0 0 0-7.48 1A2.5 2.5 0 0 0 4.5 10Zm0-3a1 1 0 0 0 1-1a2 2 0 0 1 3.89-.64a1 1 0 0 0 .78.66A1 1 0 0 1 11 7a1 1 0 0 1-1 1H4.5a.5.5 0 0 1 0-1ZM19 2h-5a1 1 0 0 0 0 2h5a1 1 0 0 1 1 1v7H3a1 1 0 0 0-1 1v2a3 3 0 0 0 3 3h3v2H5a1 1 0 0 0 0 2h14a1 1 0 0 0 0-2h-3v-2h3a3 3 0 0 0 3-3V5a3 3 0 0 0-3-3Zm-5 18h-4v-2h4Zm6-5a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-1h16Z"></path></svg>
+  )
+}
diff --git a/components/Icons/LifeRing.tsx b/components/Icons/LifeRing.tsx
@@ -0,0 +1,7 @@
+import { SVGProps } from "react";
+
+export function UilLifeRing(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1.5em" height="1.5em" viewBox="0 0 24 24" {...props}><path fill="currentColor" d="M22 11.05v-.33l-.09-.6l-.09-.39c0-.17-.08-.34-.13-.51s-.08-.27-.13-.4a2.17 2.17 0 0 1-.07-.24s0 0 0-.05a10.1 10.1 0 0 0-5.9-5.9s0 0-.05 0l-.23-.07l-.42-.13c-.15 0-.31-.08-.46-.12l-.46-.1l-.46-.07c-.16 0-.31 0-.48-.06s-.35 0-.52 0L12 2h-.91c-.17 0-.32 0-.48.06l-.46.07l-.46.1c-.15 0-.31.07-.46.12l-.42.13l-.23.07h-.05a10.1 10.1 0 0 0-5.9 5.9s0 0 0 .05a2.17 2.17 0 0 1-.07.24c0 .13-.09.26-.13.4s-.09.34-.13.51l-.09.39l-.09.6v2.56l.09.6l.09.39c0 .17.08.34.13.51s.08.27.13.4a2.17 2.17 0 0 1 .07.24a.43.43 0 0 1 0 .07a10 10 0 0 0 5.89 5.88s0 0 .05 0l.24.07l.4.13l.51.13l.39.09l.6.09h.33c.31 0 .63.05.95.05s.64 0 .95-.05h.33l.6-.09l.39-.09l.51-.13l.4-.13l.24-.07h.05a10 10 0 0 0 5.89-5.88a.43.43 0 0 1 0-.07c0-.08.05-.16.07-.24s.09-.26.13-.4s.09-.34.13-.51l.09-.39l.09-.6v-.33c0-.31.05-.63.05-.95s.09-.56.09-.87Zm-6.3-6.16a8 8 0 0 1 3.46 3.46l-2.86 1a5.14 5.14 0 0 0-1.64-1.64Zm-5.36-.7c.21-.05.41-.08.61-.11h.24a8.24 8.24 0 0 1 1.72 0h.24c.2 0 .4.06.61.11h.06l-1 2.86A4.49 4.49 0 0 0 12 7a4.4 4.4 0 0 0-.73.06l-1-2.86Zm-1.94.7l1 2.86a5.14 5.14 0 0 0-1.65 1.64l-2.86-1a8 8 0 0 1 3.46-3.5Zm-4.21 8.82a4.17 4.17 0 0 1-.1-.6v-.25a7.42 7.42 0 0 1 0-1.72v-.25a4.17 4.17 0 0 1 .1-.6s0 0 0-.06l2.86 1a4.47 4.47 0 0 0 0 1.46l-2.86 1v.02Zm4.16 5.4a8 8 0 0 1-3.46-3.46l2.86-1a5.14 5.14 0 0 0 1.64 1.64Zm5.36.7c-.21.05-.41.08-.61.11h-.24a8.24 8.24 0 0 1-1.72 0h-.24c-.2 0-.4-.06-.61-.11h-.06l1-2.86a4.47 4.47 0 0 0 1.46 0l1 2.86Zm-.67-5c-.17.06-.34.1-.5.14a2.73 2.73 0 0 1-1 0c-.16 0-.33-.08-.5-.14A3 3 0 0 1 9.2 13a3.23 3.23 0 0 1-.14-.51a2.63 2.63 0 0 1 0-1a3.23 3.23 0 0 1 .13-.49A3 3 0 0 1 11 9.2c.17-.06.34-.1.5-.14a2.73 2.73 0 0 1 1 0c.16 0 .33.08.5.14a3 3 0 0 1 1.8 1.8a3.23 3.23 0 0 1 .14.51a2.63 2.63 0 0 1 0 1a3.23 3.23 0 0 1-.14.51A3 3 0 0 1 13 14.8Zm2.61 4.31l-1-2.86a5.14 5.14 0 0 0 1.64-1.64l2.86 1a8 8 0 0 1-3.5 3.49ZM20 12.86v.25a4.17 4.17 0 0 1-.1.6s0 0 0 .06l-2.86-1a4.47 4.47 0 0 0 0-1.46l2.86-1v.06a4.17 4.17 0 0 1 .1.6v.25a7.42 7.42 0 0 1 0 1.72Z"></path></svg>
+  )
+}
diff --git a/components/Icons/MasterCard.tsx b/components/Icons/MasterCard.tsx
@@ -0,0 +1,7 @@
+import { SVGProps } from "react";
+
+export function UimMasterCard(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1.5em" height="1.5em" viewBox="0 0 24 24" {...props}><path fill="currentColor" d="M15.273 18.728A6.728 6.728 0 1 1 22 11.999V12a6.735 6.735 0 0 1-6.727 6.728z" opacity=".5"></path><path fill="currentColor" d="M8.727 18.728A6.728 6.728 0 1 1 15.455 12a6.735 6.735 0 0 1-6.728 6.728z"></path></svg>
+  )
+}
diff --git a/components/Icons/SearchAlt.tsx b/components/Icons/SearchAlt.tsx
@@ -0,0 +1,7 @@
+import { SVGProps } from "react";
+
+export function UilSearchAlt(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1.5em" height="1.5em" viewBox="0 0 24 24" {...props}><path fill="currentColor" d="M21.07 16.83L19 14.71a3.08 3.08 0 0 0-3.4-.57l-.9-.9a7 7 0 1 0-1.41 1.41l.89.89a3 3 0 0 0 .53 3.46l2.12 2.12a3 3 0 0 0 4.24 0a3 3 0 0 0 0-4.29Zm-8.48-4.24a5 5 0 1 1 0-7.08a5 5 0 0 1 0 7.08Zm7.07 7.07a1 1 0 0 1-1.42 0l-2.12-2.12a1 1 0 0 1 0-1.42a1 1 0 0 1 1.42 0l2.12 2.12a1 1 0 0 1 0 1.42Z"></path></svg>
+  )
+}
diff --git a/pages/docs/features.mdx b/pages/docs/features.mdx
@@ -33,6 +33,12 @@ Mix Space 的 Markdown 除了支持标准的 Markdown 语法和 GFM 外，还支
 - 反垃圾评论，使用 Mix Space 的反垃圾评论系统配合多种自定义规则，可以有效的防止垃圾评论
 - 邮件通知，当有人评论时，会发送邮件通知给文章作者
 
+## xLog 集成
+
+通过 Mix Space 的 xLog 功能，你可以将你的博客文章同步到 [xLog 平台](https://xlog.app)。并且当你没有为文章写摘要的时候，可以直接使用 xLog 平台生成的摘要，当然你也可以使用自己的 GPT API Key 去调用 GPT 生成文章摘要。
+
+> [xLog](https://xlog.app/about) 是面向所有人的最棒的链上、开源的博客社区。
+
 ## 文件管理
 
 你可以使用 Mix Space 上传文件，然后在任意地方中使用，比如文章中，或者是日记中。你可以使用 Markdown 语法插入图片，也可以使用 HTML 语法插入图片。
@@ -66,6 +72,6 @@ Mix Space 还有很多其他功能，比如：
 - 动态化配置前端，你可以在后台设置前端的配置，比如网站名称，网站描述，网站图标等等
 - 终端功能，你可以在后台进入终端，执行一些命令，比如清除缓存，备份数据等等
 - 云函数，你可以在后台设置云函数，让你的网站更加强大
-- Algolia Search，你可以在后台设置 Algolia Search，让你的网站支持强大的搜索功能
+- Algolia Search，你可以在后台设置 Algolia Search，让你的网站支持站内搜索功能
 - 项目展示功能，你可以向访客展示你的项目，展现你的技术能力
-- 迁移，Mix Space 支持从 Markdown 导入文章，也支持导出文章为 Markdown。
+- 迁移，Mix Space 支持从 Markdown 导入文章，也支持导出文章为 Markdown。
diff --git a/pages/usage/_meta.json b/pages/usage/_meta.json
@@ -0,0 +1,15 @@
+{
+  "index": "使用指南",
+  "-- built-in": {
+    "type": "separator",
+    "title": "官方指南"
+  },
+  "macros": "文本宏",
+  "serverless": "云函数",
+  "xlog": "xLog 集成",
+  "search": "Algolia Search",
+  "-- community": {
+    "type": "separator",
+    "title": "社区使用指南"
+  }
+}
diff --git a/pages/usage/index.mdx b/pages/usage/index.mdx
@@ -0,0 +1,29 @@
+# 使用指南
+
+本章节将会带您了解 Mix Space 的一些功能，以及如何使用它们。
+
+import { Callout } from 'nextra/components';
+
+<Callout>
+温馨提示：此指南需要一定的基础知识 & 理解能力，请准备好哦～
+</Callout>
+
+
+### 官方指南
+
+import { Cards, Card } from 'nextra/components';
+import { UimMasterCard } from '@components/Icons/MasterCard';
+import { UilCloudDatabaseTree } from '@components/Icons/CloudDatabaseTree';
+import { UilLifeRing } from '@components/Icons/LifeRing';
+import { UilSearchAlt } from '@components/Icons/SearchAlt';
+import { UilBitcoin } from '@components/Icons/Bitcoin';
+
+<Cards num={3}>
+  <Card icon={<UimMasterCard />} arrow href={"/usage/macros"} title="文本宏" />
+  <Card icon={<UilCloudDatabaseTree />} arrow href={"/usage/serverless"} title="云函数" />
+  <Card icon={<UilLifeRing />} arrow href={"/usage/bark"} title="Bark 通知  (WIP)" />
+  <Card icon={<UilSearchAlt />} arrow href={"/usage/search"} title="Algolia Search" />
+  <Card icon={<UilBitcoin />} arrow href={"/usage/xlog"} title="xLog 集成" />
+</Cards>
+
+### 社区使用指南
diff --git a/pages/usage/macros.mdx b/pages/usage/macros.mdx
@@ -0,0 +1,95 @@
+# 文本宏
+
+
+import { Callout } from 'nextra/components';
+
+<Callout type="warning">
+这是一个实验性特征，可能会造成系统的不稳定。
+
+经过测试，使用大量文本宏会造成请求文章的接口变慢。
+</Callout>
+
+## 简介
+
+<Callout type="info">
+使用此功能需要先在后台中开启，设置 - 系统 - 文本设定 - 文本宏替换。
+</Callout>
+
+Required: **mx-server >=3.26.0**
+
+文本宏是一个以 `[[ ]]` 包裹的语法，例如 `[[ $created ]]` 是一个合法的语法。在文章中可以插入文本宏，和 Markdown 一样，但是这个语法不是用 Markdown 解析和渲染，而是直接会在服务端进行替换。因此可以通过这个特征在文章中插入一些来自服务端的数据，也可以执行一些函数。
+
+例如说一篇文章的标题为「实例标题」，他的正文内容为：
+
+``` /[[ $title ]]/
+一个句子。[[ $title ]]
+```
+
+将会输出：
+
+```md /实例标题/
+一个句子。实例标题
+```
+
+又比如说：
+
+```md /[[ #dayjs($modified).format('YY-MM') ]]/
+<p align="right">更新于 [[ #dayjs($modified).format('YY-MM') ]]</p>
+```
+
+将会输出：
+
+```md /22-04/
+<p align="right">更新于 22-04</p>
+```
+
+这是一个动态的数据，`dayjs` 函数由服务端提供。
+
+
+<Callout type="warning">
+所有的函数方法均在服务端执行，请注意内存的泄露造成系统的不稳定。
+</Callout>
+
+
+## 语法格式
+
+以 `[[ ` 开头，` ]]` 结尾，注意一个空格是必须的。
+
+### 访问变量
+
+访问变量使用 `$` 前缀。目前可以访问的变量有：当前记录的所有字段（数据库记录值）比如说：`title` `created` `slug` `nid` `_id` ..
+
+你可以像这样来调用变量：`[[ $created ]]`
+
+### 使用函数
+
+<Callout type="warning">
+函数的执行行为和云函数的执行行为保持一致。
+</Callout>
+
+执行函数使用 `#` 前缀。你可以使用任意 JS 代码去执行一个函数，也可以是一个 JS 语句。
+
+如：
+
+```
+[[ #$title.slice(0, 5) ]]
+```
+
+使用内置方法。
+
+如：
+
+```
+[[ #dayjs($created).format('YYYY') ]]
+```
+
+内置方法目前有：
+
+- [dayjs](https://day.js.org/zh-CN/) —— 日期处理
+- `formatNow(time: Date | string): string` —— 相对时间
+- `center(text: string): string` —— 居中
+- `right(text: string): string` —— 居右
+- `opacity(text: string, opacity: number): string` —— 透明文本
+- `blur(text: string, blur: number): string` —— 高斯模糊化文字
+- `color(text: string, color: string): string` —— 给文字上色
+- `size(text: string): string` —— 给文字上色
diff --git a/pages/usage/search.mdx b/pages/usage/search.mdx
@@ -0,0 +1,54 @@
+# Algolia Search
+
+import { Steps } from 'nextra/components';
+
+## 介绍
+
+Algolia 是一个数据库实时搜索服务，能够提供毫秒级的数据库搜索服务，并且其服务能以 API 的形式方便地布局到网页、客户端、APP 等多种场景。
+
+像 VuePress 官方文档就是使用的 Algolia 搜索，使用 Algolia 搜索最大的好处就是方便，它会自动爬取网站的页面内容并构建索引，你只用申请一个 Algolia 服务，在网站上添加一些代码，就可以实现一个全文搜索功能。
+
+## 使用
+
+在这之前，你需要先在 Algolia 官网注册一个账号，或者直接用第三方登录。
+
+<Steps>
+
+### 新建应用
+
+登录 Algolia 账号，进入控制台，在左上角点击 Applications 下列表，点击 `New Application`，填写应用名称，选择 `BUILD` 订阅（免费），选择好数据中心，点击 `Create Application`，即可创建一个应用。
+
+一些额外说明的地方都在图片上标注了，可参考下面的图片。
+
+![](https://pan.vinua.cn/f/XL2Uv/5a93eadc694a7b7cb2898c63a6ebcf88.png)
+
+![](https://pan.vinua.cn/f/xnosz/0d41807b6594531b77163951f7092150.png)
+
+![](https://pan.vinua.cn/f/Emph7/097d062c7ebe6e322be260e3862e7762.png)
+
+![](https://pan.vinua.cn/f/bNEHK/47fcfe70a3b81e8eca2ad96e2aeae17c.png)
+
+### 创建索引（Index）
+
+在新建应用之后，你会直接跳转到如下图所示的界面，只需要在输入框中输入一个索引名称，点击 `Create Index`，即可创建一个索引。
+
+请记住你所创建的索引名称（Index Name），后面的步骤会用到。
+
+![](https://pan.vinua.cn/f/BEdhW/fbf020ae604f07e7d1ed7894c6dec35e.png)
+
+
+### 获取相关变量
+
+接下来，在左下角找到齿轮图标，进入设置，在右侧找到 `API Keys`，进入，这里有两个变量需要复制下来备用，分别是 `Application ID` 和 `Admin API Key`，请复制下这两个变量的值，后面的步骤会用到。
+
+![](https://pan.vinua.cn/f/Np6hO/ab5bdbb18af590cb3aeacba7b5861ce6.png)
+
+### 后台配置
+
+进入后台，设定->系统->Algolia Search，将“开启 Algolia Search”开关打开，将前面准备的 `IndexName`、`Application ID（AppID）` 和 `Admin API Key（ApiKey）` 填入对应的框中，右上角保存即可。
+
+![](https://pan.vinua.cn/f/DeGsA/3331ccce7fe57e4bfd87217998223f30.png)
+
+</Steps>
+
+至此，Algolia 搜索的配置就完成了。稍等一会，就可以尝试在主页用 `Ctrl + K` 调用 Algolia 进行站内搜索了。
diff --git a/pages/usage/serverless.mdx b/pages/usage/serverless.mdx
@@ -0,0 +1,35 @@
+# 云函数
+
+import { ToGitHub } from '@components/ToGitHub';
+import { Steps } from 'nextra/components';
+
+## 介绍
+
+云函数是 Mix Space 中的一个重要功能，它极大地辅助了使用者在 Mix Space 中的体验。通过云函数，Mix Space 可以额外实现实现歌单解析，追番列表等等的功能。
+
+你可以在此处看到 Mix Space 目前收录的云函数 Snappets
+
+<ToGitHub repo="mx-space/snippets" />
+
+## 使用
+
+有一些前端主题需要使用云函数，这个时候你需要进入到云函数设置界面，将云函数代码填入到对应的位置。
+
+<Steps>
+### 1. 进入云函数设置界面
+进入后台管理，点击左侧菜单栏的 `其他 - 云函数`，即可进入云函数管理页面。
+
+### 2. 下载扩展包
+
+在右上方，点击 `下载拓展包`，你将会看到一个弹窗。
+
+### 3. 导入
+
+请在弹窗内请找到对应的主题的云函数代码，点击导入，即可完成下载对应的云函数代码。
+</Steps>
+
+接下来，你可以在云函数管理页面看到你刚刚导入的云函数代码。
+
+## 开发者文档
+
+<ToGitHub repo="mx-space/core/blob/master/apps/core/src/modules/serverless/serverless.readme.md" />
diff --git a/pages/usage/xlog.mdx b/pages/usage/xlog.mdx
@@ -0,0 +1,23 @@
+# xLog 集成
+
+## 介绍
+
+此功能需要：
+
+- Core: >=3.43.1
+
+xLog 功能可以将你的博客同步到 [xLog 平台](https://xlog.app/)。
+
+具体就是 `此文章已经由它的创作者签名并安全地存储在区块链上。`
+
+当你没有为文章写摘要的时候，可以使用 xLog 平台生成的摘要，当然你也可以使用自己的 GPT API Key 去调用 GPT 去生成摘要。
+
+## 使用
+
+在 系统 - 第三方服务集成，填写 xLog SiteId 即可，然后去 xLog 平台去升级为钱包登录即可。钱包的注册方法请根据 xLog 的引导一步步注册。
+
+SiteId 是一个字符串，可以在 xLog 平台的设置 - 域名找到；例如 example.xlog.app，即 `SiteId = example`。
+
+当你完成钱包的注册，并使用钱包登录 xLog 平台的时候，就完成设置工作了。
+
+接下来你发布文章的时候，会自动的进行同步和签名；当然，需要经过你的同意。
