Icarus用户指南 - 主题配置

Icarus 主题配置详解

Icarus 的默认主题配置文件为 _config.icarus.yml。此文件定义了站点全局的布局与样式设置，同时也控制了例如插件与挂件等外部功能的配置。本文详细介绍了本主题的一般配置，并且解释了 Icarus 使用哪些配置文件和它是如何生成并验证这些配置。

本文同时提供以下语言的翻译： English.

一般主题配置

配置文件版本

这个版本号与主题版本号相关却不总是相同。Icarus 使用此版本号来决定是否升级默认主题配置文件。请不要自己更改这个版本号。

1
2
_config.icarus.yml
version: 5.0.0

主题变体

通过此设置为 Icarus 更换”皮肤”。此设置目前支持”default”和”cyberpunk”两种值。你可以在此处查看 Cyberpunk 变体的效果。

1
2
_config.icarus.yml
variant: default

设置你站点的 logo。此 logo 会显示在导航栏和页脚。logo 配置的值既可以是你的 logo 图片的路径或 URL 地址：

1
2
_config.icarus.yml
logo: /img/logo.svg

也可以像下面这样设置成文字：

1
2
3
_config.icarus.yml
logo:
    text: My Beautiful Site

Favicon

你可以在 head 配置中指定你的网站 favicon 的路径或 URL 地址。

1
2
3
_config.icarus.yml
head:
    favicon: /img/favicon.svg

Web App Manifest

Icarus 支持基本的 PWA manifest.json 的生成与 Meta 标签。要开启 web app manifest，请再主题配置中使用如下的配置。你也可以参考 MDN 来了解每个配置项的详情。

1
_config.icarus.yml

Open Graph

你可以在 head 配置中设置 Open Graph。你应该在配置文件中将绝大部分配置留空。仅在需要的时候在文章的 front-matter 中为这些设置赋值。请参考 Hexo 文档来详细了解每个配置项。

1
_config.icarus.yml

Google Structured Data

你可以在 head 配置中设置 Google Structured Data。你应该在配置文件中将绝大部分配置留空。仅在需要的时候在文章的 front-matter 中为这些设置赋值。请参考 Search for Developers 来详细了解每个配置项。

1
_config.icarus.yml

页面元信息

你可以通过 head 部分的 meta 设置来向生成的 HTML 中添加自定义 <meta> 标签。每一个 meta 标签应作为 meta 数组中的一个元素出现。meta 设置每一个元素的值应为 <属性名>=<属性值> 的格式，其中属性名和属性值分别代表着 <meta> 标签的属性和值。如果 <meta> 标签有多个属性和值，请使用 ; 来分隔 <属性名>=<属性值>。

1
2
3
4
5
_config.icarus.yml
head:
    meta:
        - 'name=theme-color;content=#123456'
        - 'name=generator;content="Hexo 4.2.0"'

RSS

你可以通过 head 部分的 rss 设置来添加 RSS 链接信息。

1
2
3
_config.icarus.yml
head:
    rss: /path/to/atom.xml

导航栏

navbar 部分定义了导航栏中的菜单与链接。你可以通过向 menu 设置项中添加 <链接名>: <链接URL> 的方式添加任意导航栏菜单链接。如要向导航栏右侧添加链接，请向 links 设置项中添加 <链接名>: <链接URL>。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
_config.icarus.yml
navbar:
    # 导航栏菜单项
    menu:
        Home: /
        Archives: /archives
        Categories: /categories
        Tags: /tags
        About: /about
    # 导航栏右侧的链接
    links:
        GitHub: 'https://github.com'
        Download on GitHub:
            icon: fab fa-github
            url: 'https://github.com/ppoffice/hexo-theme-icarus'

你也可以使用 FontAwesome 图标来作为纯文字链接的替换，格式如下：

1
2
3
4
链接格式
<链接名>:
    icon: <FontAwesome图标的class名>
    url: <链接URL>

页脚

footer 部分定义了页脚右侧的链接。链接的配置格式与 navbar 中 links 的配置格式完全一致。

1
2
3
4
5
6
7
8
9
10
11
12
_config.icarus.yml
footer:
    links:
        Creative Commons:
            icon: fab fa-creative-commons
            url: 'https://creativecommons.org/'
        Attribution 4.0 International:
            icon: fab fa-creative-commons-by
            url: 'https://creativecommons.org/licenses/by/4.0/'
        Download on GitHub:
            icon: fab fa-github
            url: 'https://github.com/ppoffice/hexo-theme-icarus'

你也可以在页脚展示自定义版权文字：

1
2
3
_config.icarus.yml
footer:
    copyright: 用💖发电

代码高亮

如果你已在 Hexo 中启用了代码高亮功能，你可以通过 article 中的 highlight 设置来自定义代码块。请从 highlight.js/src/styles 下列出的所有主题中选择一个主题。然后，复制文件名(不带.css 后缀)到 theme 设置项中。

如要隐藏复制代码按钮，将 clipboard 设置为 false。如果你希望折叠或展开所有代码块，将 fold 设置为”folded”或”unfolded”。你也可以将 fold 设置为空来禁止代码块折叠。

1
2
3
4
5
6
7
8
9
10
_config.icarus.yml
article:
    highlight:
        # 代码高亮主题
        # https://github.com/highlightjs/highlight.js/tree/master/src/styles
        theme: atom-one-light
        # 显示复制代码按钮
        clipboard: true
        # 代码块的默认折叠状态。可以是"", "folded", "unfolded"
        fold: unfolded

此外，你可以在 Markdown 文件中使用下面的语法来折叠单独的代码块：

1
2
3
{% codeblock "可选文件名" lang:代码语言 >folded %}
...代码块内容...
{% endcodeblock %}

封面 & 缩略图

若要为文章添加封面图，请在文章的 front-matter 中添加 cover 选项：

1
2
3
4
5
post.md
title: Icarus快速上手
cover: /gallery/covers/cover.jpg
---
Post content...

类似地，你也可以在文章的 front-matter 中为文章设置缩略图：

1
2
3
4
5
post.md
title: Icarus快速上手
thumbnail: /gallery/covers/thumbnail.jpg
---
Post content...

文章的缩略图会显示在归档页面和最新文章挂件中。

如果你在 front-matter 中使用的是图片的路径，你需要确保它是绝对或者相对于你的 source 目录的路径。例如，为使用 <your blog>/source/gallery/image.jpg 作为缩略图，你需要在 front-matter 中使用 /gallery/image.jpg 作为图片路径。

文章阅读时间

你可以将 article 部分的 readtime 设置为 true 来显示文章字数统计以及预计阅读时间。

1
2
3
_config.icarus.yml
article:
    readtime: true

文章更新时间

若要显示文章的更新时间，请在文章的 front_matter 中设置 updated 时间：

1
2
3
4
5
post.md
title: Icarus快速上手
updated: 2020-04-01 00:00:00
---
Post content...

然后，将主题配置文件的 article 部分的 update_time 设置为 true：

1
2
3
_config.icarus.yml
article:
    update_time: true

你也可以将 update_time 设置为 false 来隐藏所有文章的更新时间，或设置为 auto 而在文章的更新时间与发布时间相同时隐藏更新时间。

文章许可协议

你可以在你的文章/页面的底部展示你的作品的使用许可，许可链接可以是文字或者图标。这里的配置与导航栏或者页脚的 links 配置一致：

1
2
3
4
5
6
7
8
_config.icarus.yml
article:
    # 文章许可协议
    licenses:
        Creative Commons:
            icon: fab fa-creative-commons
            url: 'https://creativecommons.org/'
        'CC BY-NC-SA 4.0': 'https://creativecommons.org/licenses/by-nc-sa/4.0/'

侧边栏

设置 sidebar 中某个侧边栏的 sticky 为 true 来让它的位置固定而不跟随页面滚动。

1
2
3
4
5
6
_config.icarus.yml
sidebar:
    left:
        sticky: false
    right:
        sticky: true

其他配置

你可以参考 Icarus 用户指南来了解更多第三方的插件、挂件、以及 CDN 提供商的配置。

配置文件与优先级

除了在 _config.icarus.yml 的默认主题配置文件外，Icarus 也会从如下位置获取替代配置：

  • 位于 _config.yml 的站点配置文件
  • 位于 _config.post.yml 和 _config.page.yml 的布局配置文件
  • 文章/页面的 front-matter
  • (已弃用) 位于 themes/icarus/_config.yml 的旧主题配置文件
  • (已弃用) 位于 themes/icarus/_config.post.yml 和 themes/icarus/_config.page.yml 的旧布局配置文件

布局配置文件

布局配置文件遵循着与主题配置文件相同的格式和定义。_config.post.yml 中的配置对所有文章生效，而 _config.page.yml 中的配置对所有自定义页面生效。这两个文件将覆盖主题配置文件中的配置。

例如，你可以在 _config.post.yml 中把所有文章变为两栏布局：

1
2
3
4
5
6
7
8
9
10
11
_config.post.yml
widgets:
    -
        type: recent_posts
        position: left
    -
        type: categories
        position: left
    -
        type: tags
        position: left

同时所有其他页面仍保持三栏布局：

1
2
3
4
5
6
7
8
9
10
11
_config.icarus.yml
widgets:
    -
        type: recent_posts
        position: left
    -
        type: categories
        position: right
    -
        type: tags
        position: right

文章/页面的 Front-matter

如果你只想要在某个文章/页面中覆盖主题配置，你可以在那个文章/页面的 front-matter 中写下配置。例如，你可以像下面这样在一篇文章的 front-matter 中更改某篇文章的代码高亮主题：

1
2
3
4
5
6
7
8
source/_post/some-post.md
title: 我的第一篇文章
date: '2015-01-01 00:00:01'
article:
    highlight:
        theme: atom-one-dark
---
# 文章标题

上面的配置会为那篇文章覆盖掉 _config.post.yml 和 _config.icarus.yml 中的 article.highlight。这种层次化的配置系统对于页面个性化和不同访客间的差异化优化十分有效。比如，你可以为根据你页面目标访客的国家和语言来开启更快的 CDN 或本地化的评论服务。

然而需要注意的是，一些 Hexo 定义的文章或页面属性不会覆盖掉其他配置源中的同名配置，如 title, date, updated, comments (not comment), layout, source, photos, 和 excerpt。

站点配置文件

上面列出的所有配置源，包括主题配置文件，布局配置文件，和文章/页面的 front-matter，会覆盖掉站点配置文件中 Icarus 使用到的配置。例如，_config.icarus.yml 中的 title 设置会覆盖掉 _config.yml 中的 title，但 new_post_name 却不会，因为 Icarus 没有用到这个配置项。

另外，主题配置文件中的 theme_config 选项会与主题配置文件中的主题配置合并并覆盖掉同名配置。然而，我们非常不推荐使用这个配置选项。

总结

总而言之，配置源的作用范围和优先级如下：

对于某个文章或页面

  1. 文章/页面的 front-matter 覆盖所有下面的配置源。
  2. 布局配置文件覆盖所有下面的配置源。
  3. 站点配置文件中的 theme_config 选项覆盖所有下面的配置源。
  4. 主题配置文件覆盖所有下面的配置源。
  5. 站点配置文件。

对于所有的文章或页面

  1. 布局配置文件覆盖所有下面的配置源。
  2. 站点配置文件中的 theme_config 选项覆盖所有下面的配置源。
  3. 主题配置文件覆盖所有下面的配置源。
  4. 站点配置文件。

对于所有的文章，页面，和索引页

  1. 站点配置文件中的 theme_config 选项覆盖所有下面的配置源。
  2. 主题配置文件覆盖所有下面的配置源。
  3. 站点配置文件。

配置生成与校验

所有的 Icarus 主题配置均使用 YAML 语言编写。如果配置文件不存在，Icarus 会通过一系列 JSON Schema 来自动生成默认的配置文件 _config.icarus.yml。这也是为什么你在主题目录下找不到示例配置文件(如 _config.yml.example)。大多数的 JSON Schema 存放在 <icarus_directory>/include/schema 目录下，而其他的则存放在 ppoffice/hexo-component-inferno 仓库中。你可以在你的 hexo 命令后附上 --icarus-dont-generate-config 来避免配置文件的自动生成。

当你每次运行 hexo 命令时，主题也会对比 JSON Schema 来校验你的配置文件。如果校验中出现任何错误，Icarus 会将错误位置与错误类型打印在屏幕上。例如，如下的错误信息告诉我们 logo 配置值应该为字符串或是对象，而不是一个整型数。你可以在你的 hexo 命令后附上 --icarus-dont-check-config 来跳过校验，但并不推荐这么做。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
hexo日志
INFO  === Checking package dependencies ===
INFO  === Checking the configuration file ===
WARN  Configuration file failed one or more checks.
WARN  Icarus may still run, but you will encounter unexcepted results.
WARN  Here is some information for you to correct the configuration file.
WARN  [
  {
    keyword: 'type',
    dataPath: '.logo',
    schemaPath: '#/properties/logo/type',
    params: { type: 'string,object' },
    message: 'should be string,object'
  }
]

此外，如果你的默认主题配置文件不是最新版本的话，Icarus 会运行迁移脚本将它升级到最新版本。这些脚本存放在 <icarus_directory>/include/migration 目录。你可以在你的 hexo 命令后附上 --icarus-dont-upgrade-config 来禁止配置升级。最后，Icarus 也会检查主题依赖的 Node.js 库是否安装并提醒你安装缺失的库。