Halo-theme-joe2.0 食用文档

👀 预览主题

📗 使用文档

🌈 安装 & 更新

⚠️ 必读

🔧 主题配置

⭐️ 主题功能

✨ 改进点

📃 TODO

📈 项目状态

📚 开发指南

🔍 代码规范

项目默认配置了 husky 和 lint-staged，在 commi 阶段通过 eslint 和 stylelint 对代码进行自动格式化，然后打包，保证最终提交代码的规范性。

🤔 常见问题

如何自定义导航条菜单图标？

主题自身已经引入了部分 iconfont 图标，你可以直接用（全在这里），如果想在这个基础上增加图标，可联系我加入该项目的图标组，加入后即可获取最新的字体链接进行替换（template/module/link.ftl 中第 25 行）。iconfont 使用方式如下：

（目前主题菜单只支持字体图标，若要用图片请自行修改代码）

<i class="joe-font joe-icon-xxx"></i>

如果你要用自己的图标，请往下看：

首先通过 iconfont 获取自己的图标链接，也可以用 fontawesome 的字体，注意要使用 font-class 类型，最后得到这种地址：//at.alicdn.com/t/font_2788564_1f1rnuqwnzj.css
通过 管理后台-外观-主题-Joe2.0-设置-自定义，将图标地址贴入 字体图标链接 中并保存；
通过 管理后台-外观-菜单，为相关菜单添加图标，也就是字体图标的类名，类似如下这种（字体名称 + 图标名称，具体以你生成时的字体名为准），记得保存；

iconfont icon-home

最后，重新进入你的博客即可看到效果。

如何隐藏单个菜单？

有时你可能想临时隐藏某个菜单，但是不想删除（目前后台管理中并没提供隐藏功能）。此时你可以通过 `管理后台-外观-菜单`，在相关菜单的标题前面添加 `#hide` 标志，然后保存即可（给父菜单添加后，子菜单也会隐藏）。

如何配置邮件服务？

Halo 已经提供好了邮件服务，我们只需要配置相关参数即可。请参见《Halo 博客配置邮件通知服务》

文章页面

a、文章页元数据（postMetaField）

字段名	值类型	默认值	描述
enable_aside	Boolean	true	是否启用侧边栏
enable_page_meta	Boolean	true	是否展示页面元信息（即顶部的字数、阅读量等数据）
enable_passage_tips	Boolean	true	是否展示温馨提示
enable_collect_check	Boolean	true	是否启用百度收录检查
enable_read_limit	Boolean	false	是否开启评论后可见
use_raw_content	Boolean	false	是否渲染原始内容
enable_comment	Boolean	true	是否启用评论功能
enable_toc	Boolean	true	是否启用 Toc 目录
toc_depth	Number	0	Toc 目录默认展开层级 0~6，对应标题层级 h1 ～ h6
img_align	String	“center”	图片对齐方式（left-左对齐；center-居中；right-右对齐）
img_max_width	String	“100%”	图片最大宽度
enable_copy	Boolean	true	是否允许复制内容
enable_donate	Boolean	true	是否启用打赏（必须配置好相应二维码）
enable_share	Boolean	true	是否启用分享
enable_like	Boolean	true	是否启用点赞
code_theme	String	“one-dark”	指定代码主题（默认和全局设置一致）
enable_fold_long_code	Boolean	true	是否开启长代码块自动折叠
enable_katex	Boolean	false	是否启用公式支持

b、自定义页元数据（sheetMetaField）

字段名	值类型	默认值	描述
enable_aside	Boolean	true	是否启用侧边栏
enable_page_meta	Boolean	true	是否展示页面元信息（即顶部的字数、阅读量等数据）
enable_collect_check	Boolean	true	是否启用百度收录检查
use_raw_content	Boolean	false	是否渲染原始内容
enable_comment	Boolean	true	是否启用评论功能
img_align	String	“center”	图片对齐方式（left-左对齐；center-居中；right-右对齐）
img_max_width	String	“100%”	图片最大宽度
enable_katex	Boolean	false	是否启用公式支持

如何支持数学公式和 Mermaid 图形？

主题已经提供了对 数学公式 和 Mermaid图形 的支持，数学公式使用 Katex 进行渲染，默认为关闭状态，需要手动打开。

必须先在后台管理-外观-主题设置-文章页中启用数学公式支持

$\sum_{i=0}^N\int_{a}^{b}g(t,i)\text{d}t$
$$\Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,.$$

对于要展示 时序图、UML类图、甘特图 等的场景，需要使用代码块包裹内容，并指定语言类型为 mermaid，Halo 会自动将它转换为 svg 给前台展示。（下面的示例是一个 UML类图，更多用法大家可以去 Mermaid 仓库查看）。

```mermaid
classDiagram

Class01 <|-- AveryLongClass : Cool
<<interface>> Class01
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
class Class10 {
  <<service>>
  int id
  size()
}```

代码块如何设置自定义标题？

目前，代码块的标题来自我们设置的语言类型，如果未设置或者未匹配到语言，则显示 PlainText。

然而，你可能想要自定义代码块的标题，这时只要在 markdown 中像下面这样使用代码块即可（语言类型和标题之间用 “|” 隔开）：

```js|这是我的第一行代码
console.log("hello world!!!");```

文章中如何插入网易云播放器？

主题已集成 APlayer，只需要在编辑文章时使用 joe-music 标签插入视频地址即可，它接受如下属性：
- id：网易云歌单 ID 或歌曲 ID（可从歌曲网址中获取）

歌单

<joe-mlist id="6800335663"></joe-mlist>

单曲

<joe-music id="1303046498"></joe-music>

文章中如何插入视频？

主题已集成 dplayer，只需要在编辑文章时使用 joe-dplayer 标签插入视频地址即可（建议 MP4 格式，其它格式未必支持，切记前后要空一行），它接受如下属性：

src：视频地址（必传）
width：阅读器宽度，默认为 100%
height：阅读器高度，默认 500px

<joe-dplayer src="https://xxx.mp4"></joe-dplyer>

如果你想嵌入 B站视频，可以使用 joe-bilibili 标签（切记前后要空一行），它接受如下属性（相关参数可以从视频地址中获取）。

bvid：视频的 id（必传）
page：视频的 page，即分页
width：阅读器宽度，默认为 100%
height：阅读器高度，默认 500px

<joe-bilibili bvid="BV12h411k7vr"></joe-bilibili>

文章中如何预览 PDF 文件？

主题已集成 PDF.js，可以渲染 pdf 文件，只需要在编辑文章时使用 joe-pdf 标签插入即可（切记前后要空一行），它接受如下属性：

src：PDF 文件地址（必传），不要过长，且不能包含 &、? 等特殊字符，若出现跨域问题需要自行解决
width：阅读器宽度，默认为 100%
height：阅读器高度，默认 500px

<joe-pdf src="https://xxx.pdf" width="100%" height="500px"></joe-pdf>

如何渲染原始内容？

主题默认对常用的 HTML 标签进行了样式美化，但有时候你可能不想应用这些样式。比如你想富文本内容中的样式能够原样展示，那么就需要用到这个标签来承载你的内容，该标签内的内容将不会被外部样式和脚本污染，反之亦然。

<joe-raw-content>
  <div id="_raw">你的原始文本或html内容</div>
</joe-raw-content>

如果你在后台新建文章时，想直接用其它地方复制过来的富文本内容，那么需要你配置当前文章的元数据，把其中的 use-raw-content
的值改成 true。这样前台就会自动使用 joe-raw-content 这个标签去展示，但目前主题不支持解析富文本中的目录，请知悉。

如何修改/定制评论组件？

当前主题使用了定制的评论组件 halo-comment-joe2.0，有兴趣可以在此基础上继续定制，最后替换 source/lib/halo-comment 下的同名文件。

登录页如何显示找回密码按钮？

有时候登录后台管理系统忘了密码，想找回密码，但是界面默认没有找回密码的按钮，需要用快捷键触打开。

目录CONTENT