🌈 Halo-theme-joe2.0 食用文档

Joe 主题 Halo 移植版

Joe2.0 是 Typecho Themes Joe 主题的 Halo 版，由于社区之前有兄弟移植过，这次就叫 Joe2.0 吧，此次在原版主题上做了不少修改和适配，由原版的 php 模板调整为 freemarker，移除了平台无关的特性，同时增加了一些平台特定的配置，保持灵活性的同时最大限度的移植了原版功能，希望大家喜欢 ❤️

🌸 同时也要在此感谢原作者 Joe，欢迎大家加入 Joe2.0 交流群：850501175

👀 预览主题

📗 使用文档

效果图 👇

效果图

🌈 安装 & 更新

安装前请确保 Halo版本 和主题的兼容性，V1.0.10 及以上版本仅支持 Halo 1.5+，以下版本兼容到 Halo 1.4.11，请知悉。

复制主题仓库地址 https://github.com/qinhua/halo-theme-joe2.0.git
进入博客后台管理 外观-主题-安装-远程下载，贴入仓库地址进行安装（建议直接使用最新版本）。
如果在线安装失败（大概率失败 😆 ），那就选择 本地上传，到主题 Release 页面下载指定版本主题压缩包，并上传上去（务必在 Release 页面下载压缩包，否则可能出现资源加载出错的问题）；
等待提示安装完成即可；
更新主题时，建议直接通过 外观-主题-Joe2.0-更多-从主题包更新 把下载好的 zip 包上传上去，然后 先切换到其他主题，再切回本主题，并进入主题设置执行一次保存，最后强刷前端页面即可（这里切主题主要是为了避免有时候主题状态未激活和缓存的问题）。

如果 github 访问不了，可以访问 gitee 仓库：https://gitee.com/duider/halo-theme-joe2.0

⚠️ 必读

安装主题后请务必到 后台管理 - 博客设置 - 高级选项 中开启 API服务 并配置 Access key 为 joe2.0（切记要和主题设置中的 AccessKey 一致），不然部分用到 Content API 的页面会请求失败并报错。（请参考以下报错）

“API has been disabled by blogger currently” —— 后台管理中未开启API服务 “API access key is mismatch” —— 主题中的 AccessKey 和后台管理中的不一致

配置AccessKey

如果后台管理中之前已经配置了其它的 Access Key（内容不是 joe2.0），那么需要你到本主题设置中的 基本设置-AccessKey<必填> 同步一下这个 Access key，保证两部一致即可（切记一致才行，且不要填写中文或特殊字符）。
有时，主题升级后配置项变化较大，直接访问博客可能会报错，导致页面渲染不出来。此时，只需要进入当前主题的设置界面执行一下保存操作来更新旧的配置，然后再访问页面即可；
有时，明明已经提示主题更新成功了，但访问博客时页面还是加载的旧版本的文件，可能是由于 主题激活状态不正常 或 主题缓存的问题 导致的。此时，只需要先启用其他主题再启用本主题即可，建议每次更新主题之后都做一下这个操作（目前后台管理系统还不太完善）。还有就是如果你配置了 CDN 服务，记得清理相应节点的缓存，让它回源取最新资源。
强烈建议 每次更新主题后，务必先清空一下浏览器缓存，保证加载的资源都是最新版本的，并到主题设置中执行一次保存，保证配置项是最新的，不然可能有各种报错（你可以通过 Ctrl + F5 强制刷新或者 Ctrl + Shift + DEL 清空浏览器所有缓存）。
最后，建议大家在 后台管理-系统-博客设置-高级选项-其他设置 中开启 全局绝对路径。

🔧 主题配置

此次修改对外暴露了大量的设置项，主要是为了最大程度方便用户对博客进行配置，详细设置项请参见主题根目录下的 settings.yaml 文件。

主题配置

⭐️ 主题功能

此次在功能上做了大量移植，在尽量不破坏原主题风格的情况下，加入了 halo 主题常见的配置项，也融入了一些自己的改进 🤔。
具体功能请在 后台 -> 外观 -> 主题 -> 设置 中进行配置，配置项已按不同场景分类，便于快速查找。

浅色/暗黑模式
三级导航
轮播图 <可配置数据源>
精品分类 <可配置数据源>
自定义主题色
自定义字体
自定义背景图
自定义社交渠道
归档页定制<按年/月统计>
日志页面定制
文章分享
Toc 目录 <可通过文章设置单独控制>
代码高亮 + 行号 + 复制 + 折叠
文章和日志页点赞 + 评论
文章页 a 标签新页面打开
文章页复制加版权文字
文章内容评论后可见
播放器插件/B 站视频
PDF 插件
留言页面
网易歌单
博主可选头像框
博主等级展示
全局预载图自定义
缺省图片配置
每日一句
百度收录查询 + 主动推送
页面加载条
离屏提醒
网站公告
二维码模块
3D 标签云
看板娘
图库页面定制
自定义邮件模板
空白页模板
社交账号配置
二维码打赏
广告配置 <侧边栏 + 文章页>
页面元数据控制
自定义 JS/CSS
自定义 favicon <支持视频、动图>
站点运行时间
绿色模式 <备案模式>
灰色模式 <RIP 模式>

✨ 改进点

meta 标签优化
ftl 模板格式化
导航栏优化
页脚调整
评论组件定制
SEO 优化
样式优化
- 使用 Less
- 根据主题模式调整了部分配色
- 优化 z-index 属性
- 滚动优化
代码优化
代码风格
- Eslint + Stylelint
JS 和 CSS 兼容性处理
- JS 使用 Babel 转换
- CSS 引入 autoprefixer
页面性能优化
- 按需引入
- 图片懒加载
- DNS 预解析
- Gzip
加载状态优化
- 加载条
- 预载图
- 错误图
- 空白状态
404 页面
去除无用配置
项目目录调整
- 简化目录
部分缺陷修复
解析主题配置项

📃 TODO

目前仍有部分功能不完善，暂时没时间做或受限，后面继续迭代。

欢迎页面
统计页面
集成统计插件
视频背景
相册页优化
升级评论组件（头像保存等）
自定义模板引擎
字号调整
Pjax
博客备份

📈 项目状态

项目状态

📚 开发指南

1、推荐使用 VSCode 开发，首先安装 EasyLess 插件来转换并压缩 less 文件，保存时会自动生成 *.min.css 文件，配置如下：

"less.compile": { "out": "./min/", "outExt": ".min.css", "compress": true, "sourceMap": false, "autoprefixer": "> 2%, last 2 versions, not ie 6-9" }

2、安装 JS & CSS Minifier 插件来转换并压缩 js 文件，保存时会自动生成 *.min.js 文件，配置如下：

"es6-css-minify.js": { "mangle": false, "compress": { "unused": true }, "output": { "quote_style": 0 }, "warnings": true }, // 保存时自动生成，no 为手动，可点击编辑器底部 Minify 按钮生成 "es6-css-minify.minifyOnSave": "yes", "es6-css-minify.jsMinPath": "/source/js/min"

3、转换并压缩 ES6+ 代码（前 2 步里的 js 没有经过 babel 编译，只可用于开发环境）：

安装 nodejs；
主题目录下执行 npm i 安装依赖；
执行 npm run build 即可在相应目录生成可用于生产环境的 js 和 css 文件。

🔍 代码规范

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

🤔 常见问题

主要是一些开发及使用过程中暴露出来的问题，在这里统一列出来方便大家查阅。

1、如何获取当前主题的配置信息？

可以通过 window.ThemeConfig 直接获取。

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

主题自身已经引入了部分 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
最后，重新进入你的博客即可看到效果。

3、如何配置多级菜单？

Halo 后台目前支持配置 3 级及以上的菜单，当前主题已支持最多 3 级菜单。你需要到 管理后台-外观-菜单 中先建好要用的菜单，然后使用鼠标拖拽相应菜单，调整到你想要的顺序和结构（上下拖动是排序，左右拖动是改变层级，多尝试几次，不太灵敏）。

多级菜单

4、如果一个菜单有子菜单，如何禁止父菜单跳转？

通过 管理后台-外观-菜单，设置相关菜单的地址为 #，保存即可，子菜单同理；
最后，重新进入你的博客即可看到效果。

tips: 为了适配和展示效果，不建议添加过多菜单。目前最多可展示 3 级。

5、子菜单如何设置新页面打开？

通过 管理后台-外观-菜单，设置菜单的打开方式为 新页面，保存即可。

6、如何隐藏单个菜单？

有时你可能想临时隐藏某个菜单，但是不想删除（目前后台管理中并没提供隐藏功能）。

此时你可以通过 管理后台-外观-菜单，在相关菜单的标题前面添加 #hide 标志，然后保存即可（给父菜单添加后，子菜单也会隐藏）。

隐藏单个菜单

7、如何配置邮件服务？

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

8、如何添加留言页/空白页？

主题中的留言页面是自定义页面，所以需要你进入 后台管理-页面 ，点击 新建页面 添加留言页，记得填写 页面标题、别名，并选择自定义模板 leaving 进行发布。最后进入 外观-菜单 添加刚才自定义的留言页，保存后刷新前台页面即可，其它自定义页面同理。

目前支持的 自定义模板 有 3 种：

empty：完全空白不带任何资源的空页面，适合独立开发一个新页面的场景。
only_header_footer：仅包含导航条和页脚的空页面，适合在当前博客基础上进行开发的场景。
leaving：当前主题内已定制的 留言页 模板，可直接使用。

添加留言页

9、如何配置自定义轮播图数据？

目前主题中的轮播图支持 7 种数据来源，默认的手动模式需要我们自己配置数据，为了减少表单数量提高灵活性，使用了约定格式的方式来配置，具体规则如下：

多个轮播图之间用 ===== 隔开
属性之间用 -|||- 隔开
为了美观，允许换行
不需要跳转写 # 即可

🐧 请严格按照此格式或默认示例进行配置，否则可能导致网站崩溃，以下为示例，可复制到表单中编辑（首页精品分类 同理）：

`轮播1标题
-|||-
轮播1副标题
-|||-
轮播1图片链接
-|||-
轮播1跳转链接

轮播2标题
-|||-
轮播2副标题
-|||-
轮播2图片链接
-|||-
#`

10、修改主题中的 CSS 或 JS 后页面为什么还是引入的旧文件？

目前主题静态资源默认从源站加载，也可以配置 CDN。

请先确认 是否是浏览器缓存 导致的，清除下缓存试试；
检查 修改的文件是否是实际加载的文件，生产环境的 js 文件对应 source/js/min 目录，css 文件对应 source/css/min 目录
检查是否在主题设置中配置了 自定义CDN域名，如果配置了，可能是由于 CDN 节点缓存导致的，可以选择自行刷新目录缓存，让它回源取最新资源，或者关闭 CDN 直接从源站获取静态资源。

<link rel="preload stylesheet" as="style" href="${BASE_RES_URL}/source/css/min/index.min.css?v=${theme.version!}" />

其中 ${BASE_RES_URL} 为静态资源域名，默认为 ${theme_base!}，即主题目录，如果配置了 CDN，那就是 CDN 域名 + theme_base。

11、如何通过元数据为页面进行单独的功能配置？

这里以文章详情页为例进行说明。

很多时候，我们希望能够单独控制文章详情页的功能，如分享、打赏、复制、点赞、评论、目录等。主题目前已经为文章详情页暴露了常用的元数据配置，具体大家可以查看 theme.yaml 文件中的 postMetaField 字段。（自定义页面对应字段 sheetMetaField）
如果想通过元数据来单独控制页面功能，可以到 后台管理-文章-所有文章 中找到要修改的文章，然后点击设置，再点击底部保存按钮旁的 高级，即可在弹框中对元数据进行配置，字段格式和主题配置是一致的，布尔值填 true 或 false，都是字符串形式。

文章详情页元数据配置

🍢 具体元数据请参考下面的表格。

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

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

是否启用公式支持

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

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

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

` $\sum_{i=0}^N\int_{a}^{b}g(t,i)\text{d}t$

目录CONTENT

Halo-theme-joe2.0 食用文档

🌈 Halo-theme-joe2.0 食用文档

👀 预览主题

🌈 安装 & 更新

⚠️ 必读

🔧 主题配置

⭐️ 主题功能

✨ 改进点

📃 TODO

📈 项目状态

📚 开发指南

🔍 代码规范

🤔 常见问题

1、如何获取当前主题的配置信息？

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

3、如何配置多级菜单？

4、如果一个菜单有子菜单，如何禁止父菜单跳转？

5、子菜单如何设置新页面打开？

6、如何隐藏单个菜单？

7、如何配置邮件服务？

8、如何添加留言页/空白页？

9、如何配置自定义轮播图数据？

`轮播1标题
-|||-
轮播1副标题
-|||-
轮播1图片链接
-|||-
轮播1跳转链接

10、修改主题中的 CSS 或 JS 后页面为什么还是引入的旧文件？

11、如何通过元数据为页面进行单独的功能配置？

a、文章页元数据（postMetaField）

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

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

评论区

Halo-theme-joe2.0 食用文档

🌈 Halo-theme-joe2.0 食用文档

👀 预览主题

🌈 安装 & 更新

⚠️ 必读

🔧 主题配置

⭐️ 主题功能

✨ 改进点

📃 TODO

📈 项目状态

📚 开发指南

🔍 代码规范

🤔 常见问题

1、如何获取当前主题的配置信息？

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

3、如何配置多级菜单？

4、如果一个菜单有子菜单，如何禁止父菜单跳转？

5、子菜单如何设置新页面打开？

6、如何隐藏单个菜单？

7、如何配置邮件服务？

8、如何添加留言页/空白页？

9、如何配置自定义轮播图数据？

`轮播1标题 -|||- 轮播1副标题 -|||- 轮播1图片链接 -|||- 轮播1跳转链接

10、修改主题中的 CSS 或 JS 后页面为什么还是引入的旧文件？

11、如何通过元数据为页面进行单独的功能配置？

a、文章页元数据（postMetaField）

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

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

评论区

`轮播1标题
-|||-
轮播1副标题
-|||-
轮播1图片链接
-|||-
轮播1跳转链接