Kratos-Rebirth食用说明

  1. 1. 安装提示
  2. 2. 主题配置
    1. 2.1. - Global 全局配置
    2. 2.2. - Top Menu 顶部导航栏相关
    3. 2.3. - Footer 页脚显示相关
    4. 2.4. - Post Page 文章页面相关
    5. 2.5. - Disqus 评论相关
    6. 2.6. - DisqusJS 评论相关
    7. 2.7. - Vanila 评论相关
    8. 2.8. - APlayer 音乐播放器相关(页面左下角)
    9. 2.9. - Widgets 侧边栏与挂件
    10. 2.10. - FancyBox 图片放大显示
    11. 2.11. - Search 搜索
    12. 2.12. - JsConfig JavaScript 调用需要的系列配置项
    13. 2.13. - Code Highlight Themes 代码高亮主题
    14. 2.14. - Site verify related 站点所有权验证相关
  3. 3. 文章页面
  4. 4. 模板与特定页面
  5. 5. 模板特有标签组件
    1. 5.1. 提示信息
    2. 5.2. 折叠内容
    3. 5.3. 提示面板
  6. 6. 关于MathJax对公式进行的处理
  7. 7. 关于Hexo书写的小技巧

是时候写一个文档了!(被打死
如果有什么遗漏的地方欢迎随时向我提出!可以用留言的方式(但有时候邮箱会收不到邮件,比较怨念),或者去Github提一个Issue~
文档会尽可能在两边都保持更新,所以只要我没忘记的话应该是没什么大问题哒(光速逃跑)


安装提示

由于本模板使用了和默认模板landscape一样的ejs引擎,因此当您完成Hexo站点的安装后,您应该能够直接运行本主题。

但为了进一步提升您的使用体验,我们推荐您安装以下插件:

  • hexo-generator-index-pin-top
  • hexo-generator-feed

在运行之前,请您将_config.yml.example文件复制一份,并重命名为_config.yml

主题配置

配置文件地址:./kratos-rebirth/_config.yml

- Global 全局配置

  • site_analytics: 站点统计代码,这一行代码会被插入到后页脚。

  • hoster: 网站托管服务提供者,这个是出于感恩性的可选添加内容,这一个链接会被插入到后页脚。

  • site_logo: 网站的LOGO图片文件,请注意与后面核心JS的设置保持一致。

  • snow: (true/false)站点下雪特效开关,控制是否在载入下雪相关的代码。

  • enableDark: (true/false)站点是否启用暗色模式适配。请注意,即使启用了暗色模式,在亮色的环境下主题仍然会渲染为亮色模式;同时用户可以手动选择使用的颜色(右下角菜单栏按钮处)。

  • mathjax: (true/false)站点是否启用MathJax支持(可用于渲染各种公式)。相关的使用提示可以参阅文末的提示部分

  • cdn (true/false)为静态资源开启CDN加速(使用jsDelivr)。请注意,如果您修改了任何静态资源,那么请保持此项为false(同时也是默认状态)

  • indexPostType (true/false)站点首页是否使用文章主题的显示模式(即一开始可见一部分,点击阅读更多可以加载全文,Hexo许多主题都默认的显示模式(而不是默认的这种卡片式的陈列方式)

- Top Menu 顶部导航栏相关

  • 分为menulabel两个模块,控制页首的顶部导航栏内容。
    menu模块提供导航到的页面位置,label模块提供导航选项卡的显示内容。
    请注意menu项与label项需要一一对应,否则可能会出现无法正常显示的情况。
    配置样例随主题附带,可以参考使用。

  • 现已加入二级菜单支持,配置格式为:

1
2
3
4
5
6
7
8
9
10
11
12
13
menu:
二级菜单:
submenu: true
菜单项1: 地址1
菜单项2: 地址2
...

label:
二级菜单:
submenu: 菜单显示内容
菜单项1: 菜单项1显示内容
菜单项2: 菜单项2显示内容
...

请注意关键词submenu不可被改变,其他内容在保证一一对应的情况下可以自定义。
具体可以参照主题自带的样例配置。

额外提示:二级菜单功能可能会和旧版本的部分函数发生冲突,如果出现意外报错的话可以考虑检查一下是否存在更新的Hexo版本,或者去Github提一个Issue
此处附上目前开发使用的环境(package.json文件):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
"name": "hexo-site",
"version": "0.0.0",
"private": true,
"scripts": {
"build": "hexo generate",
"clean": "hexo clean",
"deploy": "hexo deploy",
"server": "hexo server"
},
"hexo": {
"version": "5.2.0"
},
"dependencies": {
"hexo": "^5.2.0",
"hexo-generator-archive": "^1.0.0",
"hexo-generator-category": "^1.0.0",
"hexo-generator-feed": "^2.2.0",
"hexo-generator-index-pin-top": "^0.2.2",
"hexo-generator-sitemap": "^2.1.0",
"hexo-generator-tag": "^1.0.0",
"hexo-renderer-ejs": "^1.0.0",
"hexo-renderer-marked": "^3.3.0",
"hexo-renderer-stylus": "^1.1.0",
"hexo-server": "^1.0.0"
}
}
  • group_link: 控制是否在页面右下角显示群聊的加入按钮。如果显示的话,这里可以指定加群的链接。无需显示的话请留空(而不是删除这个设置项),相关的代码会自行处理结构生成关系。

  • contact: 联系方式相关,控制是否在页脚(./kratos-rebirth/layout/_partial/footer.ejs)显示各种联系方式的按钮
    如果要启用的话,请输入相关联系方式的代码,直接输入用户名即可(fediverse的实例需要输入实例地址,邮箱请使用mail@example.com这样的格式);无需显示的内容请留空。

  • timenotice: 本站运行时间前的提示文本。

  • icp: ICP备案号,便于生成快捷链接,如萌ICP备22010101号

  • psr: 公安备案号,便于生成快捷链接,如371402000001

- Post Page 文章页面相关

  • show_cc: (true/false)控制文章页面(./kratos-rebirth/layout/post.ejs)是否显示CreativeCommon知识共享协议相关的提示内容w

  • donate: (true/false)控制文章页面是否显示捐助的二维码按钮,二维码链接可以在站点的JS里进行修改(详见下文)

  • share: (true/false)控制文章页面是否显示分享链接的按钮

  • comments: (disqus/disqusjs/vanila/false)是想要使用原生的disqus呢,还是试着配置一下disqusjs来提升使用体验呢?如果不想开启评论的话,那就还是设置为false吧~

- Disqus 评论相关

- DisqusJS 评论相关

这里使用了DisqusJS这个项目,具体的参数配置相关的可以参考原始文档,这里提供的说明仅供参考w

- Vanila 评论相关

- APlayer 音乐播放器相关(页面左下角)

  • enabled: (true/false)用音乐来点缀全新的体验吧!这里可以选择是否开启aplayer播放器哦~

  • playlist: APlayer播放使用的歌单地址,可以使用公开的API服务,或是搭建自己使用的后端。
    我提供了一个后端API的样例,目前本站点使用的就是这个,可以去Github获取。

  • order: (list/random)音乐播放的顺序,我个人比较喜欢的是random模式,这样就能避免每次访问博客时,都是从第一首音乐开始播放的尴尬清情况。

- Widgets 侧边栏与挂件

  • sidebar: (left/right/none)是否启用侧边栏与小工具,若设置为left则会显示在页面左侧,若设置为right则会显示在页面右侧。

  • widgets: 启用的小部件,默认全部启用,不喜欢的就删掉吧w

  • avataUri: 头像的图片地址链接,例如我用的是gravatar

- FancyBox 图片放大显示

  • fancybox: (true/false)启用图片放大显示工具,点击文章内的图片可以进行全屏放大操作

- Search 搜索

  • enable: (true/false)是否启用站点搜索功能

  • path: 搜索数据库的文件名,一般保持默认search.json即可

  • field: 搜索的区域,可以是页面,或是文章,或是所有内容。默认情况下是仅搜索文章内容。

  • content: (true/false)搜索内容是否包含文章或是页面的详细内容

- JsConfig JavaScript 调用需要的系列配置项

  • main: 主JavaScript配置
    • picCDN (true/false)图片是否使用CDN来载入(如果有本地替换过图片的话,请千万不要设置成true)
    • createTime 站点建立的时间,请改成您站点建立的时间。该项与页脚的运行时间有直接关联,建议按照样例格式进行书写,以免出现莫名其妙的报错。
    • donateBtn 捐助按钮上显示的文字,建议不要太长以免溢出,如果不显示捐助按钮的话就不用去管它啦~
    • kr.scanNotice 二维码小窗口上的小标题,如果不显示捐助按钮的话也不用去管它啦~
    • qr_alipay 支付宝二维码的文件地址
    • qr_wechat 微信支付二维码的文件地址
    • siteLeaveEvent (true/false)是否启用站点失焦事件(只是为了卖萌,有可能会影响到历史记录,请谨慎开启)
    • leaveTitle 离开时候站点标题的追加内容
    • returnTitle 返回时候站点标题的追加内容

- Code Highlight Themes 代码高亮主题

  • highlight_theme: 主题,五选一(normal | night | night eighties | night blue | night bright),控制代码高亮时候使用的配色,请在src/css/highlight.css中自行编辑并压缩样式表文件。
  • site_verify:
    • google: Google Search,只填写中间那一串随机码即可
    • baidu: 百毒搜索,同样只需填写中间的一串随机码
    • bing: 必应搜索,同样只需填写中间的一串随机码

文章页面

配置路径:顶部,文章信息区 (Front-Matter)

  • pic: 可以指定这篇文章是否使用自定义的缩略图名称(在文章资源文件夹内),而不是使用随机化的图标

  • top: (true/false)重要的文章,把它们置顶吧!会在首页优先显示哦~
    补充:请记得安装hexo-generator-index-pin-top插件。

  • comments: (true/false)是否为单篇文章指定开启或关闭评论区

  • toc: (true/false)该文章是否需要生成目录


模板与特定页面

参见项目Kratos-Rebirth-Specified-Pages


模板特有标签组件

提示信息

成功啦o(* ̄▽ ̄*)ブ
有危险Σ(っ °Д °;)っ
有消息(・∀・(・∀・(・∀・*)
当心哦≧ ﹏ ≦
1
2
3
4
{% alertbox success "成功啦o(* ̄▽ ̄*)ブ" %}
{% alertbox danger "有危险Σ(っ °Д °;)っ" %}
{% alertbox info "有消息(・∀・(・∀・(・∀・*)" %}
{% alertbox warning "当心哦≧ ﹏ ≦" %}

折叠内容

这是一条折叠内容
1
2
3
4
5
6
7
{% collapse 折叠框的标题 %}

被折叠的内容 1
被折叠的内容 2
...

{% endcollapse %}

提示面板

这是一个提示面板框
1
2
3
4
5
6
7
{% colorpanel TYPE 面板框的标题 %}

面板里的内容 1
面板里的内容 2
...

{% endcolorpanel %}

TYPE是面板框的类型,可以是:

  • successs
  • danger
  • info
  • warning

关于MathJax对公式进行的处理

由于目前文章内的内容全部都会先过一遍Hexo的Markdown解释器,因而所有的转义符都会被解释器处理(如\\会被转译成\\(会被转义成(),所以需要您手动将公式中可能出现的会被转义的内容中的单反斜杠改为双反斜杠(以此保证转义后仍然能在前端被MathJax进行转义处理)

或者如果您有安装hexo的mathjax插件,请将主题中的相关设置保持为关闭以避免可能出现的代码二次载入的情况


关于Hexo书写的小技巧

Hexo使用了MarkDown,但是在一些细节的处理上有很棒的技巧哦~

  1. 文章概要
    可以将文章开头的一段作为概要显示在首页主题部分,方法就是在需要分割的地方加入<!-- more -->即可;或者可以在文章头指定excerpt

  2. 图片资源
    Hexo有为每篇文章生成一个资源文件夹,可以将图片资源以{% asset_img 文件名 备注 %}的格式插入文章,本主题引入的fancybox会自动实现对文章内图片的放大功能。