👀 预览主题
📗 使用文档
🌈 安装 & 更新
⚠️ 必读
🔧 主题配置
⭐️ 主题功能
✨ 改进点
📃 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
,可以渲染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
下的同名文件。
登录页如何显示找回密码按钮?
有时候登录后台管理系统忘了密码,想找回密码,但是界面默认没有找回密码的按钮,需要用快捷键触打开。
- Windows/Linux: Shift + Alt + h
- maxOS: Shift + Command + h