Home

Awesome

<a id="readme" style="visibility:hidden"> </a>

<br> <p align="center"> <a class="logo" href="https://github.com/qinhua/halo-theme-joe2.0"> <img src="https://cdn.jsdelivr.net/gh/qinhua/halo-theme-joe2.0@master/logo.png" style="width:30vw;min-width:280px;max-width:500px;" alt="halo-theme-joe2.0"> </a> </p> <p align="center">Joe 主题 Halo 移植版</p> <p class="badge-row" align="center"> <a href="https://halo.run" target="_blank"> <img src="https://img.shields.io/badge/Halo-1.5.x-p" alt="Halo"/> </a> <a href="https://github.com/qinhua/halo-theme-joe2.0" target="_blank"> <img src="https://img.shields.io/badge/FreeMarker-2.3.3-blue" alt="Release"/> </a> <a href="https://github.com/qinhua/halo-theme-joe2.0" target="_blank"> <img src="https://img.shields.io/badge/Release-1.0.10-green" alt="Release"/> </a> <a href="https://halo.run" target="_blank"> <img src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-orange" alt="License"/> </a> </p>

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

<br>

👀 预览主题

📗 使用文档

<br>

效果图 👇

效果图

<!-- ![暗黑模式](https://cdn.jsdelivr.net/gh/qinhua/halo-theme-joe2.0@master/source/img/dp/shot_dark.png) ![浅色模式](https://cdn.jsdelivr.net/gh/qinhua/halo-theme-joe2.0@master/source/img/dp/shot_light.png) --> <br>

🌈 安装 & 更新

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

  1. 复制主题仓库地址 https://github.com/qinhua/halo-theme-joe2.0.git

  2. 进入博客后台管理 外观-主题-安装-远程下载，贴入仓库地址进行安装（建议直接使用最新版本 ）。 如果在线安装失败（大概率失败 😆 ），那就选择 本地上传，到主题 Release 页面下载指定版本主题压缩包，并上传上去（务必在 Release 页面下载压缩包，否则可能出现资源加载出错的问题）；

  3. 等待提示安装完成即可；

  4. 更新主题时，建议直接通过 外观-主题-Joe2.0-更多-从主题包更新 把下载好的 zip 包上传上去，然后 先切换到其他主题，再切回本主题，并进入主题设置执行一次保存，最后强刷前端页面即可（这里切主题主要是为了避免有时候主题状态未激活和缓存的问题）。

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

⚠️ 必读

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

配置AccessKey

  1. 如果后台管理中之前已经配置了其它的 Access Key（内容不是 joe2.0），那么需要你到本主题设置中的 基本设置-AccessKey<必填> 同步一下这个 Access key，保证两部一致即可（切记一致才行，且不要填写中文或特殊字符）。

  2. 有时，主题升级后配置项变化较大，直接访问博客可能会报错，导致页面渲染不出来。此时，只需要进入当前主题的设置界面执行一下保存操作来更新旧的配置，然后再访问页面即可；

  3. 有时，明明已经提示主题更新成功了，但访问博客时页面还是加载的旧版本的文件，可能是由于 主题激活状态不正常 或 主题缓存的问题 导致的。此时，只需要先启用其他主题再启用本主题即可，建议每次更新主题之后都做一下这个操作（目前后台管理系统还不太完善）。还有就是如果你配置了 CDN 服务，记得清理相应节点的缓存，让它回源取最新资源。

  4. 强烈建议 每次更新主题后，务必先清空一下浏览器缓存，保证加载的资源都是最新版本的，并到主题设置中执行一次保存，保证配置项是最新的，不然可能有各种报错（你可以通过 Ctrl + F5 强制刷新或者 Ctrl + Shift + DEL 清空浏览器所有缓存）。

  5. 最后，建议大家在 后台管理-系统-博客设置-高级选项-其他设置 中开启 全局绝对路径。

<br>

🔧 主题配置

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

主题配置

<br>

⭐️ 主题功能

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

<br>

✨ 改进点

<br>

📃 TODO

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

<br>

📈 项目状态

项目状态

<br>

📚 开发指南

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 编译，只可用于开发环境）：

<br>

🔍 代码规范

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

<br>

🤔 常见问题

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

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

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

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

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

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

菜单图标配置

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

3、如何配置多级菜单？

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

多级菜单

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

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

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

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

6、如何隐藏单个菜单？

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

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

隐藏单个菜单

7、如何配置邮件服务？

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

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

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

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

添加留言页

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

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

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

轮播1标题
-|||-
轮播1副标题
-|||-
轮播1图片链接
-|||-
轮播1跳转链接
=====
轮播2标题
-|||-
轮播2副标题
-|||-
轮播2图片链接
-|||-
#

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

目前主题静态资源默认从源站加载，也可以配置 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、如何通过元数据为页面进行单独的功能配置？

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

文章详情页元数据配置

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

a、文章页元数据（postMetaField）
字段名值类型默认值描述
enable_asideBooleantrue是否启用侧边栏
enable_page_metaBooleantrue是否展示页面元信息（即顶部的字数、阅读量等数据）
enable_passage_tipsBooleantrue是否展示温馨提示
enable_collect_checkBooleantrue是否启用百度收录检查
enable_read_limitBooleanfalse是否开启评论后可见
use_raw_contentBooleanfalse是否渲染原始内容
enable_commentBooleantrue是否启用评论功能
enable_tocBooleantrue是否启用 Toc 目录
toc_depthNumber0Toc 目录默认展开层级 0~6，对应标题层级 h1 ～ h6
img_alignString"center"图片对齐方式（left-左对齐；center-居中；right-右对齐）
img_max_widthString"100%"图片最大宽度
enable_copyBooleantrue是否允许复制内容
enable_donateBooleantrue是否启用打赏（必须配置好相应二维码）
enable_shareBooleantrue是否启用分享
enable_likeBooleantrue是否启用点赞
code_themeString“one-dark”指定代码主题（默认和全局设置一致）
enable_fold_long_codeBooleantrue是否开启长代码块自动折叠
enable_katexBooleanfalse是否启用公式支持
b、自定义页元数据（sheetMetaField）
字段名值类型默认值描述
enable_asideBooleantrue是否启用侧边栏
enable_page_metaBooleantrue是否展示页面元信息（即顶部的字数、阅读量等数据）
enable_collect_checkBooleantrue是否启用百度收录检查
use_raw_contentBooleanfalse是否渲染原始内容
enable_commentBooleantrue是否启用评论功能
img_alignString"center"图片对齐方式（left-左对齐；center-居中；right-右对齐）
img_max_widthString"100%"图片最大宽度
enable_katexBooleanfalse是否启用公式支持

12、如何支持数学公式和 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()
}
```

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

目前，代码块的标题来自我们设置的语言类型，如果未设置或者未匹配到语言，则显示 PlainText。<br> 然而，你可能想要自定义代码块的标题，这时只要在 markdown 中像下面这样使用代码块即可（语言类型和标题之间用 “|” 隔开）：

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

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

主题已集成 APlayer，只需要在编辑文章时使用 joe-music 标签插入视频地址即可，它接受如下属性：

歌单
<joe-mlist id="6800335663"></joe-mlist>
单曲
<joe-music id="1303046498"></joe-music>

15、文章中如何插入视频？

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

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

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

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

16、文章中如何预览 PDF 文件？

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

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

17、如何渲染原始内容？

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

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

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

18、如何设置文章仅评论后可见？

主题目前支持文章页的 评论后可见功能，只要在后台管理中发布文章时设置-元数据 enable_read_limit 为 true 即可。设置之后文章页默认只展示一屏高度的内容，剩余内容需要评论后才可见（如果文章内容小于一屏高度，则此功能会被忽略）。

评论后可见

19、如何区分不同的自定义页面？

有时候我们可能想在某一个自定义页面内部加入一些资源，单纯靠页面类型 sheet 无法进行区分。此时可以先进入 后台管理系统，并打开浏览器控制台，切换到 network-Fetch/XHR 这一栏，然后进入 页面-所有页面-自定义页面，此时控制面板中会出现相应的请求，查看数据获取页面对于的 id，这样我们就可以在模板中使用这个 id 区分不同的自定义页面了（可在 sheet.ftl 文件中通过 sheet.id 获取）。

自定义页面id

20、为什么评论头像不显示或加载出错？

目前主题内的头像使用了 gravatar 的头像服务，但是国内基本会被 GFW，所以会导致头像加载不出来。 此时，我们只需要去 后台管理-系统-博客设置-评论设置 中找到 Gravatar镜像源 更换可用的头像源即可，注意末尾要有 /。

另外说明一点，基于普适性考虑，当前评论组件咱不支持保存头像，统一使用了随机的 gravatar 头，可以随时切换源。

21、如何配置自定义 CDN？

为了提升站点的访问速度，我们很快会想到接入 CDN 服务，本主题支持为静态资源配置自己的 CDN 域名，具体见下面步骤：

22、如何查看博客后台日志？

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

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

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

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

25、为何主题保存时提示服务器内部错误或失败？

这个问题的原因通常有下面这些：

26、为何上传主题包会失败？

这个有很多原因，常见的原因有如下这些：

27、FreeMarker 相关技巧

主要是本人在开发主题过程中收集的一些 Freemarker 知识，希望能帮到需要的人。请参见 FreeMarker 常用技巧

<br>

😈 小建议

1、开启防盗链

# 资源防盗链（指定目录or指定文件类型）
# location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$ {
location /upload/ {
  access_log off;
  # 域名白名单，去掉则阻止所有非本站请求
  valid_referers none blocked server_names *.bbchin.com 127.0.0.1 localhost ~\.google\. ~\.baidu\. ~\.qq\.;
  if ($invalid_referer) {
    rewrite ^/ https://cdn.jsdelivr.net/gh/qinhua/cdn_assets/img/robber.jpg;
  }
  proxy_pass http://127.0.0.1:8090;
}

2、图片自动转 webp 格式

很多时候，站点会展示很多图片，比如文章封面、相册等，大量图片的加载会严重影响页面性能。在懒加载的基础上，我们最好能使用 webp 这种图片格式，因为它体积小很多（只是要考虑兼容性），但好在我们可以使用 webp_server_go 这个工具对全站图片自动进行 webp 化，提高加载速度。

这个工具会在我们请求图片时，在后台对图片进行转码压缩，并返回转换后的 webp 图片给前台，对于不兼容的浏览器，它会原样返回，保证正常展示。

具体使用请参考 如何无痛切换网站图片格式到 webp，当然，如果你使用其他云服务，他们本身已经提供了相关功能，可以直接在相关控制面板中开启，这里不再赘述。

3、配置合适的缓存策略

合理利用浏览器的缓存同样可以优化页面性能，提高加载速度，我们可以通过 Nginx 对相关资源的响应头进行配置，大致如下：

location / {
    gzip_static on; # 静态压缩
    add_header Cache-Control public,max-age=60,s-maxage=60; # 配置缓存
    proxy_set_header HOST $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://127.0.0.1:8090;
}
<br>

📈 页面性能

在页面没有大量图片和特效的场景下，各项性能指标都还不错。数据来自 Chrome 浏览器中的 Lighthouse 工具，仅供参考用。

页面性能报告

<br>

🏭 贡献

如果你想帮助完善 Joe2.0 主题，请：

<br>

🙆‍♂️ 感谢

在此感谢以下项目提供的支持：

<br> <!-- [![Open in Visual Studio Code](https://open.vscode.dev/badges/open-in-vscode.svg)](https://open.vscode.dev/qinhua/halo-theme-joe2.0) -->