github
/
hexo-theme-icarus
mirror of https://github.com/ppoffice/hexo-theme-icarus
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
hexo-theme-icarus/source/_posts/zh-CN/Configuring-Theme.md

16 KiB
Raw Blame History

title: Icarus用户指南 - 主题配置 date: 2016-01-03 categories:

  • Configuration tags:
  • Getting Started
  • Icarus用户指南 language: zh-CN toc: true providers: cdn: loli fontcdn: loli iconcdn: loli
本文同时提供以下语言的翻译：English.

Icarus的默认主题配置文件_config.yml存放在themes/icarus目录下。 此文件不仅定义了站点全局的布局与样式设置，同时也包含了例如评论系统和挂件等其他组件的配置。 本文将介绍Icarus的主题配置机制，并且简述部分常用配置的格式与含义。

配置文件生成与校验

Icarus的主题配置文件由YAML语言实现。 当你使用Hexo来处理主题文件而你的主题目录下没有默认配置文件themes/icarus/_config.yml时，Icarus会通过一系列JSON Schema文件来自动生成默认的 配置文件。 所以正常情况下你的主题目录下没有示例配置文件(_config.yml.example)并且也没有必要去手动创建_config.yml文件。 大多数的JSON Schema定义存放在themes/icarus/include/schema目录下，其他的定义则存放在ppoffice/hexo-component-inferno 仓库中。 你可以在运行hexo命令时附上--icarus-dont-generate-config来避免配置文件的自动生成。

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

{% codeblock "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' } ] {% endcodeblock %}

另外，Icarus会尝试运行迁移脚本将你的配置升级到最新版本。 这些脚本存放在themes/icarus/include/migration目录。 你可以在hexo命令后附上--icarus-dont-upgrade-config来禁止配置升级。 最后，Icarus会检查主题所依赖的Node.js库是否安装并提醒你安装缺失的组件。

额外的配置文件与优先级

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

  • themes/icarus/_config.post.yml和themes/icarus/_config.page.yml
  • 文章/页面的front-matter
  • 根目录下的站点配置文件_config.yml

_config.post.yml和_config.page.yml配置文件与默认配置文件的格式和定义相同。 你可以在_config.post.yml中设置仅对文章页面生效的配置，而这些配置将覆盖默认配置文件中的同名配置。 例如，你可以在此配置文件中把所有的挂件放置在页面左侧，从而将所有的文章页面设置为两栏布局，同时其他页面仍保持三栏布局：

{% codeblock themes/icarus/_config.yml lang:yaml %} widgets: - type: recent_posts position: left - type: categories position: right - type: tags position: right {% endcodeblock %}

{% codeblock themes/icarus/_config.post.yml lang:yaml %} widgets: - type: recent_posts position: left - type: categories position: left - type: tags position: left {% endcodeblock %}

类似的，_config.page.yml中的配置也覆盖默认配置文件中的配置，并仅对所有Hexo页面(pages)生效。 此外，如果你想要在某个文章/页面中覆盖默认配置，你可以把这些配置放在那个文章/页面的front-matter(头部)。 例如，如果你想在某篇文章中更换代码高亮主题，你可以像下面这样把配置卸载文章的front-matter中：

{% codeblock source/_post/some-post.md lang:yaml %} title: 我的第一篇文章 date: '2015-01-01 00:00:01' article: highlight: theme: atom-one-dark

文章标题

{% endcodeblock %}

上面文章头部中的配置总会覆盖掉_config.post.yml和_config.yml文件中的同名配置。 在自定义页面或者优化访客的页面访问体验时，这个功能会十分有用。 比如，你可以为某篇文章设置更快的CDN，或者根据访客的国家或语言开启本地化的评论服务。 然而需要注意的是，一些Hexo定义的文章或页面属性不会复写掉其他配置文件中的同名配置，例如：

  • title
  • date
  • updated
  • comments (not comment)
  • layout
  • source
  • photos
  • excerpt

最后，站点根目录下的配置文件_config.yml可以被其他所有配置文件中的主题使用到的配置项所覆盖。 例如，themes/icarus/_config.yml中的title设置会覆盖掉_config.yml中的title，但new_post_name却不会，因为 Icarus没有用到这个配置项。

总而言之，配置文件的范围和覆盖优先级如下

某个文章/页面
  • front-matter可以覆盖
  • themes/icarus/_config.post.yml或themes/icarus/_config.page.yml可以覆盖
  • themes/icarus/_config.yml可以覆盖
  • _config.yml
所有文章/页面
  • themes/icarus/_config.post.yml或themes/icarus/_config.page.yml可以覆盖
  • themes/icarus/_config.yml可以覆盖
  • _config.yml
所有HTML页面
  • themes/icarus/_config.yml可以覆盖
  • _config.yml

主题配置项概览

配置文件版本

{% codeblock themes/icarus/_config.yml lang:yaml %} version: 3.0.0 {% endcodeblock %}

这个版本号与主题版本号相关却不总是相同。 当Icarus通过迁移脚本升级配置文件时，这个版本号会被用到。 请不要自己更改这个版本号。

主题变体

{% codeblock themes/icarus/_config.yml lang:yaml %} variant: default {% endcodeblock %}

为Icarus更换”皮肤“。 此配置目前支持”default“和”cyberpunk“两种值。 你可以在{% post_link demo/Cyberpunk "此处" %}查看Cyberpunk变体的效果。

{% codeblock themes/icarus/_config.yml lang:yaml %} logo: /img/logo.svg {% endcodeblock %}

此项配置设置了页面导航栏和尾部展示的logo图片。 logo配置的值既可以时你的logo图片的路径或URL地址，也可以时如下这种文字形式的logo

{% codeblock themes/icarus/_config.yml lang:yaml %} logo: text: My Beautiful Site {% endcodeblock %}

Favicon

{% codeblock themes/icarus/_config.yml lang:yaml %} head: favicon: /img/favicon.svg {% endcodeblock %}

你可以在head中的favicon配置中设置你的网站的favicon图标的路径或URL地址。

Open Graph

{% codeblock themes/icarus/_config.yml lang:yaml >folded %} 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: {% endcodeblock %}

你可以在head部分配置Open Graph。 一些配置项应在主题配置文件中留空并在需要时在文章的front-matter中设置它们。 请参考Hexo文档来了解每个配置项的详细含义。

Google Structured Data

{% codeblock themes/icarus/_config.yml lang:yaml >folded %} head: structured_data: # 页面标题 (可选) # 大部分情况下请留空 title: # 页面描述 (可选) # 大部分情况下请留空 description: # 页面URL地址 (可选) # 大部分情况下请留空 url: # 页面作者 (article:author) (可选) # 大部分情况下请留空 author: # 页面图片 (可选) # 大部分情况下请留空 image: {% endcodeblock %}

你可以在head部分配置Google Structured Data。 大部分配置项应在主题配置文件中留空并在需要时在文章的front-matter中设置它们。 请参考Search for Developers来了解每个配置项的详细含义。

页面Metadata

{% codeblock themes/icarus/_config.yml lang:yaml %} head: meta: - 'name=theme-color;content=#123456' - 'name=generator;content="Hexo 4.2.0"' {% endcodeblock %}

你可以通过head部分的meta设置来向页面中添加<meta>标签。 每一个meta标签应作为meta数组中的一个元素。 标签的属性应按照<属性名>=<属性值>的格式出现并用;隔开。

RSS

{% codeblock themes/icarus/_config.yml lang:yaml %} head: rss: /path/to/atom.xml {% endcodeblock %}

你可以通过此设置在页面头部添加RSS链接信息。

导航栏

{% codeblock themes/icarus/_config.yml lang:yaml %} 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' {% endcodeblock %}

navbar部分定义了导航栏中出现的链接。 你可以通过向menu配置项中添加<链接名>: <链接URL>的方式添加任意导航栏菜单链接。 如果你希望向导航栏右侧添加链接，请向links配置项中添加<链接名>: <链接URL>。 你甚至可以使用FontAwesome图标来替换掉纯文字链接，格式如下：

{% codeblock "链接格式" lang:yaml %} <链接名>: icon: <FontAwesome图标的class名> url: <链接URL> {% endcodeblock %}

页面尾部

{% codeblock themes/icarus/_config.yml lang:yaml %} 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' {% endcodeblock %}

你可以通过向footer中的links配置项中添加添加任意链接。 链接的格式与navbar的links配置项相同。

代码高亮

{% codeblock themes/icarus/_config.yml lang:yaml %} article: highlight: # 代码高亮主题 # https://github.com/highlightjs/highlight.js/tree/master/src/styles theme: atom-one-light # 显示复制代码按钮 clipboard: true # 代码块的默认折叠状态。可以是"", "folded", "unfolded" fold: unfolded {% endcodeblock %}

如果你已在Hexo中启用了代码高亮功能，那么你可以通过article中的highlight设置来自定义代码块。 请从highlight.js/src/styles目录下选择一个高亮主题， 然后将不带.css后缀的文件名设置到theme配置项中。 你亦可以将clipboard设置为true或false来显示或隐藏复制代码按钮。 最后，如果你希望默认折叠或展开所有代码块，请将fold设置为folded或unfolded。 你也可以将其设置为空来禁止代码块折叠。 另外，你可以使用下面的语法来折叠单独的代码块：

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

缩略图

为文章设置缩略图仅需两步。 第一步，确保主题配置文件中缩略图功能已启用：

{% codeblock themes/icarus/_config.yml lang:yaml %} article: thumbnail: true {% endcodeblock %}

第二步，在文章的front-matter中设置缩略图的路径或URL地址：

{% codeblock post.md lang:yaml %} title: Icarus快速上手 thumbnail: /gallery/thumbnails/desert.jpg

文章内容... {% endcodeblock %}

文章头部的图片路径应为图片的绝对路径或URL地址，或图片相对于你网站的source目录的相对地址。 例如，如果你想使用<your blog>/source/gallery/image.jpg作为缩略图，你需要在front-matter中使用/gallery/image.jpg作为图片地址。

文章阅读时间

{% codeblock themes/icarus/_config.yml lang:yaml %} article: readtime: true {% endcodeblock %}

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

侧边栏

{% codeblock themes/icarus/_config.yml lang:yaml %} sidebar: left: sticky: false right: sticky: true {% endcodeblock %}

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

其他配置项

如果你对第三方的插件，挂件，以及CDN提供商的配置感兴趣的话，请参考Icarus用户指南系列文章。

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

Vector Landscape Vectors by Vecteezy