发表Configuration25 分钟读完 (大约3729个字)

Icarus用户指南 - 主题配置

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

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

一般主题配置

配置文件版本

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

_config.icarus.yml
1
version: 5.0.0

主题变体

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

_config.icarus.yml
1
variant: default

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

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

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

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

Favicon

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

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

Web App Manifest

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

_config.icarus.yml >folded
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
28
29
manifest:
    # Web应用的名称 (默认为站点标题)
    name: Icaurs - Hexo Theme
    # Web的显示名称
    # 当没有空间显示全名时显示
    short_name: Icarus
    # Web应用的初始URL
    start_url: https://ppoffice.github.io/
    # 应用的默认主题颜色
    theme_color: "#3273dc"
    # 在应用的样式表加载之前显示的应用页默认占位背景颜色
    background_color: "#3273dc"
    # 网站首选的展示模式
    display: standalone
    # 在不同上下文下用作应用图标的图片文件
    icons:
        -
            # 图片文件的路径
            src: icons/touch-icon-iphone.png
            # 空格分割的表示图标尺寸的字符串
            sizes: 144x144
            # 图片的媒体类型提示 (可选)
            type: image/png
        -
            src: icons/touch-icon-ipad.png
            sizes: 152x152
        -
            src: icon/logo.ico
            sizes: 72x72 96x96 128x128 256x256

Open Graph

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

_config.icarus.yml >folded
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
28
head:
    open_graph:
        # 页面标题 (og:title) (可选)
        title: 
        # 页面类型 (og:type) (可选)
        type: blog
        # 页面URL地址 (og:url) (可选)
        url: 
        # 页面封面图 (og:image) (可选)
        image: 
        # 站点名称 (og:site_name) (可选)
        site_name: 
        # 页面作者 (article:author) (可选)
        author: 
        # 页面描述 (og:description) (可选)
        description: 
        # Twitter卡片类型 (twitter:card)
        twitter_card: 
        # Twitter ID (twitter:creator)
        twitter_id: 
        # Twitter站点 (twitter:site)
        twitter_site: 
        # Google+个人主页链接 (已弃用)
        google_plus: 
        # Facebook admin ID
        fb_admins: 
        # Facebook App ID
        fb_app_id:

Google Structured Data

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

_config.icarus.yml >folded
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
head:
    structured_data:
        # 页面标题 (可选)
        title: 
        # 页面描述 (可选)
        description: 
        # 页面URL地址 (可选)
        url: 
        # 页面作者 (article:author) (可选)
        author: 
        # 页面图片 (可选)
        image: 
        # 文章发布者 (可选)
        publisher:
        # 发布者Logo (可选)
        publisher_logo:

页面元信息

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

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

RSS

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

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

导航栏

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

_config.icarus.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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
<链接名>:
    icon: <FontAwesome图标的class名>
    url: <链接URL>

页脚

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

_config.icarus.yml
1
2
3
4
5
6
7
8
9
10
11
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'

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

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

代码高亮

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

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

_config.icarus.yml
1
2
3
4
5
6
7
8
9
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选项：

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

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

post.md
1
2
3
4
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来显示文章字数统计以及预计阅读时间。

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

文章更新时间

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

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

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

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

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

文章许可协议

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

_config.icarus.yml
1
2
3
4
5
6
7
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来让它的位置固定而不跟随页面滚动。

_config.icarus.yml
1
2
3
4
5
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中把所有文章变为两栏布局：

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

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

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

文章/页面的Front-matter

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

source/_post/some-post.md
1
2
3
4
5
6
7
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选项会与主题配置文件中的主题配置合并并覆盖掉同名配置。 然而，我们非常不推荐使用这个配置选项。

总结

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

  • 对于某个文章或页面

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

  • 对于所有的文章或页面

    • 布局配置文件覆盖所有下面的配置源。
    • 站点配置文件中的theme_config选项覆盖所有下面的配置源。
    • 主题配置文件覆盖所有下面的配置源。
    • 站点配置文件。

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

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

配置生成与校验

所有的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来跳过校验，但并不推荐这么做。

hexo日志
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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库是否安装并提醒你安装缺失的库。

文章内容有误？请点击此处提交修改。

Icarus用户指南 - 主题配置

http://ppoffice.github.io/hexo-theme-icarus/Configuration/icarus用户指南-主题配置/

作者

PPOffice

发布于

2016-01-04

许可协议

CC BY-NC-SA 4.0

#
关注我

分类

标签

Demo19
Getting Started4
Icarus User Guide12
Icarus用户指南12
Your browser is out-of-date!

Update your browser to view this website correctly.&npsb;Update my browser now

×

×