github
/
hexo-theme-icarus
mirror of https://github.com/ppoffice/hexo-theme-icarus
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

chore(doc): update zh-CN getting started guides

pull/729/head
ppoffice 2020-05-05 22:01:15 -04:00
parent cfe84f139a
commit 1a88074dc2
4 changed files with 274 additions and 263 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
source/_posts/en/Configuring-Theme.md
View File

@ -56,7 +56,7 @@ The value of the `logo` can either be the path or URL to your logo image:
logo: /img/logo.svg logo: /img/logo.svg
{% endcodeblock %} {% endcodeblock %}
Or if you want the text instead, you can set it like the following: or text if you set it like the following:
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
logo: logo:
@ -149,7 +149,7 @@ head:
You can add custom `<meta>` tags to the generated HTML from the `meta` setting in the `head` section. You can add custom `<meta>` tags to the generated HTML from the `meta` setting in the `head` section.
Each meta tag should appear as an item of the `meta` array. Each meta tag should appear as an item of the `meta` array.
The value of the `meta` setting should be in the `<field_name>=<field_value>` format The value of each `meta` item should be in the `<field_name>=<field_value>` format
with `field_name` and `field_value` represent the field and value of the `<meta>` tag respectively. with `field_name` and `field_value` represent the field and value of the `<meta>` tag respectively.
Separate the `<field_name>=<field_value>` pairs with `;` if the `<meta>` tag has multiple fields and values. Separate the `<field_name>=<field_value>` pairs with `;` if the `<meta>` tag has multiple fields and values.
@ -273,7 +273,7 @@ You can add a thumbnail image to your post in two steps:
If you choose to use the image path in the front-matter, you need to ensure the path is absolute If you choose to use the image path in the front-matter, you need to ensure the path is absolute
or relative to the source directory of your site. or relative to the source directory of your site.
For example, to use `<your blog>/source/gallery/image.jpg` as a thumbnail path, you need to put For example, to use `<your blog>/source/gallery/image.jpg` as a thumbnail image, you need to put
`thumbnail: /gallery/image.jpg` in the front-matter. `thumbnail: /gallery/image.jpg` in the front-matter.
### Read Time ### Read Time
@ -384,30 +384,30 @@ Examples are:
- `photos` - `photos`
- `excerpt` - `excerpt`
Lastly, any other configuration files listed above will override the site configuration file `_config.yml` Lastly, all configuration sources listed above will override the site configuration file `_config.yml`
for the settings used by the Icarus. for the settings used by the Icarus.
For instance, `title` in the `themes/icarus/_config.yml` will override `title` in the `_config.yml`, but For instance, `title` in the `themes/icarus/_config.yml` will override `title` in the `_config.yml`, but
`new_post_name` will not since it is not used by Icarus. `new_post_name` will not since it is not used by Icarus.
In conclusion, the scopes of the configuration locations and their priorities are: In conclusion, the scopes of the configuration sources and their priorities are:
- A certain post or page - For a certain post or page
- front-matter overrides all configurations below. - front-matter overrides all configuration sources below.
- `themes/icarus/_config.post.yml` and `themes/icarus/_config.page.yml` override all configurations below. - `themes/icarus/_config.post.yml` and `themes/icarus/_config.page.yml` override all configuration sources below.
- `themes/icarus/_config.yml` overrides all configurations below. - `themes/icarus/_config.yml` overrides all configuration sources below.
- `_config.yml` - `_config.yml`.
- All posts or pages - For all posts or pages
- `themes/icarus/_config.post.yml` or `themes/icarus/_config.page.yml` override all configurations below. - `themes/icarus/_config.post.yml` or `themes/icarus/_config.page.yml` override all configuration sources below.
- `themes/icarus/_config.yml` overrides all configurations below. - `themes/icarus/_config.yml` overrides all configuration sources below.
- `_config.yml` - `_config.yml`.
- All posts, pages, and index pages - For all posts, pages, and index pages
- `themes/icarus/_config.yml` overrides all configurations below. - `themes/icarus/_config.yml` overrides all configuration sources below.
- `_config.yml` - `_config.yml`.
## Configuration Generation and Validation ## Configuration Generation and Validation
@ -423,7 +423,7 @@ generation.
The theme also validates your configurations against these schemas every time you execute a `hexo` command. The theme also validates your configurations against these schemas every time you execute a `hexo` command.
If anything goes wrong during the validation, Icarus will print out the exact location of the misconfiguration If anything goes wrong during the validation, Icarus will print out the exact location of the misconfiguration
and it's error type. and its error type.
For example, the following messages tell us that the value of the `logo` setting should be either a string or an For example, the following messages tell us that the value of the `logo` setting should be either a string or an
object, instead of an integer. object, instead of an integer.
You may skip the validation by appending the `--icarus-dont-check-config` flag to your `hexo` commands, but it is You may skip the validation by appending the `--icarus-dont-check-config` flag to your `hexo` commands, but it is

8
source/_posts/en/Getting-Started.md
View File

@ -26,7 +26,7 @@ open to a sea of improvement possibilities.
Before you continue to the installation of Icarus, take some time to review the Before you continue to the installation of Icarus, take some time to review the
[Hexo documentation](https://hexo.io). [Hexo documentation](https://hexo.io).
To install Icarus, download the tarball from the GitHub and extract it to your Hexo blog's theme To install Icarus, download the source code tarball from the GitHub and extract it to your Hexo site's theme
directory. directory.
Alternatively, you can use Git to clone the Icarus repository to the `themes` directory: Alternatively, you can use Git to clone the Icarus repository to the `themes` directory:
@ -34,15 +34,15 @@ Alternatively, you can use Git to clone the Icarus repository to the `themes` di
git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b <version number> --depth 1 git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b <version number> --depth 1
{% endcodeblock %} {% endcodeblock %}
You may omit `-b <version number>` to get the latest development version of Icarus. You can omit `-b <version number>` to get the latest development version of Icarus.
You may also leave `--depth 1` out if you want to download full Git commit history of Icarus as well. Leave `--depth 1` out if you want to download full Git commit history of Icarus as well.
Furthermore, you can install Icarus as a Git submodule with the following command: Furthermore, you can install Icarus as a Git submodule with the following command:
{% codeblock "Git Bash/Shell" %} {% codeblock "Git Bash/Shell" %}
git submodule add https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus git submodule add https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus
{% endcodeblock %} {% endcodeblock %}
Next, activate Icarus in your blog's `_config.yml` file: Next, activate Icarus in your site's `_config.yml` file:
{% codeblock _config.yml lang:yaml %} {% codeblock _config.yml lang:yaml %}
theme: icarus theme: icarus

440
source/_posts/zh-CN/Configuring-Theme.md
View File

@ -13,196 +13,58 @@ providers:
iconcdn: loli iconcdn: loli
--- ---
<div class="notification is-success is-size-6"> Icarus的默认主题配置文件为`themes/icarus/_config.yml`。
本文同时提供以下语言的翻译：<a href="{% post_path en/Configuring-Theme %}">English</a>. 此文件定义了站点全局的布局与样式设置，同时也控制了例如插件与挂件等外部功能的配置。
</div> 本文详细介绍了本主题的一般配置，并且解释了Icarus使用哪些配置文件和它是如何生成并验证这些配置。
Icarus的默认主题配置文件`_config.yml`存放在`themes/icarus`目录下。 <article class="message message-immersive is-primary">
此文件不仅定义了站点全局的布局与样式设置，同时也包含了例如评论系统和挂件等其他组件的配置。 <div class="message-body">
本文将介绍Icarus的主题配置机制，并且简述部分常用配置的格式与含义。 <i class="fas fa-globe-americas mr-2"></i>本文同时提供以下语言的翻译：
<a href="{% post_path en/Configuring-Theme %}">English</a>.
</div>
</article>
<!-- more --> <!-- more -->
## 配置文件生成与校验 <style>
.content ol:not([type]) {
list-style-type: simp-chinese-informal;
}
</style>
Icarus的主题配置文件由[YAML语言](https://yaml.org/)实现。 ## 一般主题配置
当你使用Hexo来处理主题文件而你的主题目录下没有默认配置文件`themes/icarus/_config.yml`时，Icarus会通过一系列[JSON Schema](https://json-schema.org/)文件来自动生成默认的
配置文件。
所以正常情况下你的主题目录下没有示例配置文件(`_config.yml.example`)并且也没有必要去手动创建`_config.yml`文件。
大多数的JSON Schema定义存放在`themes/icarus/include/schema`目录下，其他的定义则存放在[ppoffice/hexo-component-inferno](https://github.com/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](https://hexo.io/docs/front-matter.html)
- 根目录下的站点配置文件`_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没有用到这个配置项。
总而言之，配置文件的范围和覆盖优先级如下
<table class="table is-bordered is-striped">
<tr>
<th>某个文章/页面</th>
</tr>
<tr>
<td>
<ul class="mt-0 ml-4">
<li>front-matter可以覆盖</li>
<li><code>themes/icarus/_config.post.yml</code>或<code>themes/icarus/_config.page.yml</code>可以覆盖</li>
<li><code>themes/icarus/_config.yml</code>可以覆盖</li>
<li><code>_config.yml</code></li>
</ul>
</td>
</tr>
<tr>
<th>所有文章/页面</th>
</tr>
<tr>
<td>
<ul class="mt-0 ml-4">
<li><code>themes/icarus/_config.post.yml</code>或<code>themes/icarus/_config.page.yml</code>可以覆盖</li>
<li><code>themes/icarus/_config.yml</code>可以覆盖</li>
<li><code>_config.yml</code></li>
</ul>
</td>
</tr>
<tr>
<th>所有HTML页面</th>
</tr>
<tr>
<td>
<ul class="mt-0 ml-4">
<li><code>themes/icarus/_config.yml</code>可以覆盖</li>
<li><code>_config.yml</code></li>
</ul>
</td>
</tr>
<tr>
</table>
## 主题配置项概览
### 配置文件版本 ### 配置文件版本
这个版本号与主题版本号相关却不总是相同。
Icarus使用此版本号来决定是否升级默认主题配置文件。
请不要自己更改这个版本号。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
version: 3.0.0 version: 3.0.0
{% endcodeblock %} {% endcodeblock %}
这个版本号与主题版本号相关却不总是相同。
当Icarus通过迁移脚本升级配置文件时，这个版本号会被用到。
请不要自己更改这个版本号。
### 主题变体 ### 主题变体
通过此设置为Icarus更换”皮肤“。
此设置目前支持”`default`“和”`cyberpunk`“两种值。
你可以在{% post_link demo/Cyberpunk "此处" %}查看Cyberpunk变体的效果。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
variant: default variant: default
{% endcodeblock %} {% endcodeblock %}
为Icarus更换”皮肤“。
此配置目前支持”default“和”cyberpunk“两种值。
你可以在{% post_link demo/Cyberpunk "此处" %}查看Cyberpunk变体的效果。
### Logo ### Logo
设置你站点的logo。
此logo会显示在导航栏和页面尾部。
`logo`配置的值既可以是你的logo图片的路径或URL地址：
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
logo: /img/logo.svg logo: /img/logo.svg
{% endcodeblock %} {% endcodeblock %}
此项配置设置了页面导航栏和尾部展示的logo图片。 也可以像下面这样设置成文字：
`logo`配置的值既可以时你的logo图片的路径或URL地址，也可以时如下这种文字形式的logo
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
logo: logo:
@ -211,15 +73,20 @@ logo:
### Favicon ### Favicon
你可以在`head`配置中指定你的网站favicon的路径或URL地址。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
head: head:
favicon: /img/favicon.svg favicon: /img/favicon.svg
{% endcodeblock %} {% endcodeblock %}
你可以在`head`中的`favicon`配置中设置你的网站的favicon图标的路径或URL地址。
### Open Graph ### Open Graph
你可以在`head`配置中设置Open Graph。
你应该在配置文件中将绝大部分配置留空。
仅在需要的时候在文章的front-matter中为这些设置赋值。
请参考[Hexo文档](https://hexo.io/zh-cn/docs/helpers.html#open-graph)来详细了解每个配置项。
{% codeblock themes/icarus/_config.yml lang:yaml >folded %} {% codeblock themes/icarus/_config.yml lang:yaml >folded %}
head: head:
open_graph: open_graph:
@ -258,12 +125,13 @@ head:
fb_app_id: fb_app_id:
{% endcodeblock %} {% endcodeblock %}
你可以在`head`部分配置Open Graph。
一些配置项应在主题配置文件中留空并在需要时在文章的front-matter中设置它们。
请参考[Hexo文档](https://hexo.io/zh-cn/docs/helpers.html#open-graph)来了解每个配置项的详细含义。
### Google Structured Data ### Google Structured Data
你可以在`head`配置中设置Google Structured Data。
你应该在配置文件中将绝大部分配置留空。
仅在需要的时候在文章的front-matter中为这些设置赋值。
请参考[Search for Developers](https://developers.google.com/search/docs/guides/intro-structured-data)来详细了解每个配置项。
{% codeblock themes/icarus/_config.yml lang:yaml >folded %} {% codeblock themes/icarus/_config.yml lang:yaml >folded %}
head: head:
structured_data: structured_data:
@ -284,11 +152,12 @@ head:
image: image:
{% endcodeblock %} {% endcodeblock %}
你可以在`head`部分配置Google Structured Data。 ### 页面元信息
大部分配置项应在主题配置文件中留空并在需要时在文章的front-matter中设置它们。
请参考[Search for Developers](https://developers.google.com/search/docs/guides/intro-structured-data)来了解每个配置项的详细含义。
### 页面Metadata 你可以通过`head`部分的`meta`设置来向生成的HTML中添加自定义`<meta>`标签。
每一个meta标签应作为`meta`数组中的一个元素出现。
`meta`设置每一个元素的值应为`<属性名>=<属性值>`的格式，其中`属性名`和`属性值`分别代表着`<meta>`标签的属性和值。
如果`<meta>`标签有多个属性和值，请使用`;`来分隔`<属性名>=<属性值>`。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
head: head:
@ -297,21 +166,21 @@ head:
- 'name=generator;content="Hexo 4.2.0"' - 'name=generator;content="Hexo 4.2.0"'
{% endcodeblock %} {% endcodeblock %}
你可以通过`head`部分的`meta`设置来向页面中添加`<meta>`标签。
每一个meta标签应作为`meta`数组中的一个元素。
标签的属性应按照`<属性名>=<属性值>`的格式出现并用`;`隔开。
### RSS ### RSS
你可以通过`head`部分的`rss`设置来添加RSS链接信息。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
head: head:
rss: /path/to/atom.xml rss: /path/to/atom.xml
{% endcodeblock %} {% endcodeblock %}
你可以通过此设置在页面头部添加RSS链接信息。
### 导航栏 ### 导航栏
`navbar`部分定义了导航栏中的菜单与链接。
你可以通过向`menu`设置项中添加`<链接名>: <链接URL>`的方式添加任意导航栏菜单链接。
如要向导航栏右侧添加链接，请向`links`设置项中添加`<链接名>: <链接URL>`。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
navbar: navbar:
# 导航栏菜单项 # 导航栏菜单项
@ -329,10 +198,7 @@ navbar:
url: 'https://github.com/ppoffice/hexo-theme-icarus' url: 'https://github.com/ppoffice/hexo-theme-icarus'
{% endcodeblock %} {% endcodeblock %}
`navbar`部分定义了导航栏中出现的链接。 你也可以使用FontAwesome图标来作为纯文字链接的替换，格式如下：
你可以通过向`menu`配置项中添加`<链接名>: <链接URL>`的方式添加任意导航栏菜单链接。
如果你希望向导航栏右侧添加链接，请向`links`配置项中添加`<链接名>: <链接URL>`。
你甚至可以使用FontAwesome图标来替换掉纯文字链接，格式如下：
{% codeblock "链接格式" lang:yaml %} {% codeblock "链接格式" lang:yaml %}
<链接名>: <链接名>:
@ -342,6 +208,9 @@ navbar:
### 页面尾部 ### 页面尾部
`footer`部分定义了页面尾部右侧的链接。
链接的配置格式与`navbar`中`links`的配置格式完全一致。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
footer: footer:
links: links:
@ -356,11 +225,17 @@ footer:
url: 'https://github.com/ppoffice/hexo-theme-icarus' url: 'https://github.com/ppoffice/hexo-theme-icarus'
{% endcodeblock %} {% endcodeblock %}
你可以通过向`footer`中的`links`配置项中添加添加任意链接。
链接的格式与`navbar`的`links`配置项相同。
### 代码高亮 ### 代码高亮
如果你已在Hexo中启用了代码高亮功能，你可以通过`article`中的`highlight`设置来自定义代码块。
请从[highlight.js/src/styles](https://github.com/highlightjs/highlight.js/tree/9.18.1/src/styles)下列出的所有主题中
选择一个主题。
然后，复制文件名（不带`.css`后缀）到`theme`设置项中。
如要隐藏复制代码按钮，将`clipboard`设置为`false`。
如果你希望折叠或展开所有代码块，将`fold`设置为`"folded"`或`"unfolded"`。
你也可以将`fold`设置为空来禁止代码块折叠。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
article: article:
highlight: highlight:
@ -373,13 +248,7 @@ article:
fold: unfolded fold: unfolded
{% endcodeblock %} {% endcodeblock %}
如果你已在Hexo中启用了代码高亮功能，那么你可以通过`article`中的`highlight`设置来自定义代码块。 此外，你可以在Markdown文件中使用下面的语法来折叠单独的代码块：
请从[highlight.js/src/styles](https://github.com/highlightjs/highlight.js/tree/9.18.1/src/styles)目录下选择一个高亮主题，
然后将不带`.css`后缀的文件名设置到`theme`配置项中。
你亦可以将`clipboard`设置为`true`或`false`来显示或隐藏复制代码按钮。
最后，如果你希望默认折叠或展开所有代码块，请将`fold`设置为`folded`或`unfolded`。
你也可以将其设置为空来禁止代码块折叠。
另外，你可以使用下面的语法来折叠单独的代码块：
``` ```
{% codeblock "可选文件名" lang:代码语言 >folded %} {% codeblock "可选文件名" lang:代码语言 >folded %}
@ -389,37 +258,40 @@ article:
### 缩略图 ### 缩略图
为文章设置缩略图仅需两步。 你可以通过两步来为你的文章添加缩略图：
第一步，确保主题配置文件中缩略图功能已启用：
{% codeblock themes/icarus/_config.yml lang:yaml %} 1. 确保主题配置中缩略图功能已启用：
article:
thumbnail: true
{% endcodeblock %}
第二步，在文章的front-matter中设置缩略图的路径或URL地址： {% codeblock themes/icarus/_config.yml lang:yaml %}
article:
thumbnail: true
{% endcodeblock %}
{% codeblock post.md lang:yaml %} 2. 在你的文章的front-matter中提供缩略图的路径或URL地址：
title: Icarus快速上手
thumbnail: /gallery/thumbnails/desert.jpg
---
文章内容...
{% endcodeblock %}
文章头部的图片路径应为图片的绝对路径或URL地址，或图片相对于你网站的`source`目录的相对地址。 {% codeblock post.md lang:yaml %}
例如，如果你想使用`<your blog>/source/gallery/image.jpg`作为缩略图，你需要在front-matter中使用`/gallery/image.jpg`作为图片地址。 title: Icarus快速上手
thumbnail: /gallery/thumbnails/desert.jpg
---
文章内容...
{% endcodeblock %}
如果你在front-matter中使用的是图片的路径，你需要确保它是绝对或者相对于你的source目录的路径。
例如，为使用`<your blog>/source/gallery/image.jpg`作为缩略图，你需要在front-matter中使用`/gallery/image.jpg`作为图片路径。
### 文章阅读时间 ### 文章阅读时间
你可以将`article`部分的`readtime`设置为`true`来显示文章字数统计以及预计阅读时间。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
article: article:
readtime: true readtime: true
{% endcodeblock %} {% endcodeblock %}
你可以将`article`部分的`readtime`设置为`true`来显示文章字数以及预计阅读时间。
### 侧边栏 ### 侧边栏
设置`sidebar`中某个侧边栏的`sticky`为`true`来让它的位置固定而不跟随页面滚动。
{% codeblock themes/icarus/_config.yml lang:yaml %} {% codeblock themes/icarus/_config.yml lang:yaml %}
sidebar: sidebar:
left: left:
@ -428,17 +300,143 @@ sidebar:
sticky: true sticky: true
{% endcodeblock %} {% endcodeblock %}
你设置`sidebar`中的`sticky`设置项为`true`来让边栏的位置固定而不跟随页面滚动。
### 其他配置
你可以参考[Icarus用户指南](/hexo-theme-icarus/tags/Icarus用户指南/)来了解更多第三方的插件、挂件、以及CDN提供商的配置。
## 其他配置项 ## 配置文件与优先级
如果你对第三方的插件，挂件，以及CDN提供商的配置感兴趣的话，请参考[Icarus用户指南](/hexo-theme-icarus/tags/Icarus用户指南/)系列文章。 除了在`themes/icarus/_config.yml`的默认主题配置文件外，Icarus也会从如下位置获取替代配置：
- `themes/icarus/_config.post.yml`和`themes/icarus/_config.page.yml`
- 文章/页面的[front-matter](https://hexo.io/docs/front-matter.html)
- 根目录下的站点配置文件`_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`中的`article.highlight`。
这种层次化的配置系统对于在页面个性化与优化上差异化对待不同访客十分有效。
比如，你可以为根据你页面目标访客的国家和语言来开启更快的CDN或本地化的评论服务。
然而需要注意的是，一些Hexo内定义的文章或页面属性不会覆盖掉其他配置源中的同名配置，例如：
- `title`
- `date`
- `updated`
- `comments` (not `comment`)
- `layout`
- `source`
- `photos`
- `excerpt`
最后，上面列出的所有配置源中Icarus用到的配置项都会覆盖站点配置文件`_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`。
- 对于所有的文章，页面，和索引页
- `themes/icarus/_config.yml`覆盖所有下面的配置源。
- `_config.yml`。
<div class="notification is-warning is-size-6"> ## 配置生成与校验
文章内容有误？请点击<a href="https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/zh-CN/Configuring-Theme.md">此处</a>提交修改。
所有的Icarus主题配置均采用[YAML语言](https://yaml.org/)。
当Hexo加载主题时，Icarus会通过一系列[JSON Schema](https://json-schema.org/)来自动生成默认的配置文件`themes/icarus/_config.yml`。
这也是为什么你在主题目录下找不到示例配置文件(`_config.yml.example`)。
大多数的JSON Schema存放在`themes/icarus/include/schema`目录下，而其他的则存放在
[ppoffice/hexo-component-inferno](https://github.com/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库是否安装并提醒你安装缺失的库。
<article class="message message-immersive is-warning">
<div class="message-body">
<i class="fas fa-question-circle mr-2"></i>文章内容有误？请点击<a href="https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/zh-CN/Configuring-Theme.md">此处</a>提交修改。
</div> </div>
</article>
<a style="background-color:black;color:white;text-decoration:none;padding:4px 6px;font-size:12px;line-height:1.2;display:inline-block;border-radius:3px" href="https://www.vecteezy.com/free-vector/vector-landscape" target="_blank" rel="noopener noreferrer" title="Vector Landscape Vectors by Vecteezy"><span style="display:inline-block;padding:2px 3px"><svg xmlns="http://www.w3.org/2000/svg" style="height:12px;width:auto;position:relative;vertical-align:middle;top:-1px;fill:white" viewBox="0 0 32 32"><path d="M20.8 18.1c0 2.7-2.2 4.8-4.8 4.8s-4.8-2.1-4.8-4.8c0-2.7 2.2-4.8 4.8-4.8 2.7.1 4.8 2.2 4.8 4.8zm11.2-7.4v14.9c0 2.3-1.9 4.3-4.3 4.3h-23.4c-2.4 0-4.3-1.9-4.3-4.3v-15c0-2.3 1.9-4.3 4.3-4.3h3.7l.8-2.3c.4-1.1 1.7-2 2.9-2h8.6c1.2 0 2.5.9 2.9 2l.8 2.4h3.7c2.4 0 4.3 1.9 4.3 4.3zm-8.6 7.5c0-4.1-3.3-7.5-7.5-7.5-4.1 0-7.5 3.4-7.5 7.5s3.3 7.5 7.5 7.5c4.2-.1 7.5-3.4 7.5-7.5z"></path></svg></span><span style="display:inline-block;padding:2px 3px">Vector Landscape Vectors by Vecteezy</span></a>

53
source/_posts/zh-CN/Getting-Started.md
View File

@ -11,56 +11,67 @@ providers:
iconcdn: loli iconcdn: loli
--- ---
<div class="notification is-success is-size-6"> 欢迎使用Icarus！
本文同时提供以下语言的翻译：<a href="{% post_path en/Getting-Started %}">English</a>。 Icarus是静态网站生成器Hexo的一款简单，精致，而现代的主题。
</div> 它力求设计上的优雅，但也不抛弃使用上的简单明了。
它灵活且多功能的配置系统让资深用户也能极尽细节地装饰他们的站点。
Icarus同时也提供了超多插件与挂件来满足你的多元的站点个性化和优化需求。
除此以外，它的崭新实现使得更好的IDE支持和第三方接入成为可能，并提供了更多未来的优化空间。
作为静态网站生成器Hexo的一款主题，Icarus以简洁、现代和精美为设计理念。在灵活且强大的配置系统的助力下，用户可以自由实现单栏与 <article class="message message-immersive is-primary">
多栏的灵活页面布局。同时，Icarus提供了丰富的插件与挂件供用户选择，让网站的个性化配置变得触手可及。此外，得力于全新设计的API， <div class="message-body">
开发者可以更便捷地对Icarus进行深层定制。 <i class="fas fa-globe-americas mr-2"></i>本文同时提供以下语言的翻译：
<a href="{% post_path en/Getting-Started %}">English</a>.
</div>
</article>
<!-- more --> <!-- more -->
Icarus的安装非常简单，您只需从GitHub的仓库中下载Icarus源码并解压到博客的主题目录下的`themes/icarus`目录中。 在你继续安装Icarus之前，请先花些时间阅览[Hexo文档](https://hexo.io)。
您也可以使用如下命令将此主题下载到博客中： 如要安装Icarus，从GitHub的仓库中下载源码的压缩包并解压到你Hexo站点的主题目录中。
或者，你可以使用Git来克隆Icarus的代码仓库到`themes`目录下：
{% codeblock "Git Bash命令行" %} {% codeblock "Git Bash命令行" %}
git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b <version number> --depth 1 git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b <version number> --depth 1
{% endcodeblock %} {% endcodeblock %}
您可以省略`-b <version number>`来下载Icarus的最新开发版本。如果你想同时下载Git仓库的完整修改历史，请同时省略`--depth 1`。 你可以省略`-b <version number>`来获取Icarus的最新开发版本。
另外，您也可以将Icarus作为Git子模块(submodule)安装到您的博客中： 如果你想同时下载Git仓库的完整提交历史，请同时省略`--depth 1`。
另外，你也可以使用下面的命令将Icarus安装为Git子模块(submodule)：
{% codeblock "Git Bash命令行" %} {% codeblock "Git Bash命令行" %}
git submodule add https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus git submodule add https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus
{% endcodeblock %} {% endcodeblock %}
接下来，请将博客根目录下的`_config.yml`中的主题设置改为`icarus`： 接下来，在你的站点的`_config.yml`文件中的开启Icarus：
{% codeblock _config.yml lang:yaml %} {% codeblock _config.yml lang:yaml %}
theme: icarus theme: icarus
{% endcodeblock %} {% endcodeblock %}
或使用`hexo`命令修改主题设置: 或使用`hexo`命令修改主题为Icarus:
{% codeblock "命令行" %} {% codeblock "命令行" %}
hexo config theme icarus hexo config theme icarus
{% endcodeblock %} {% endcodeblock %}
最后，请使用如下命令来启动Hexo本地测试服务器。 最后，使用如下命令来启动Hexo本地测试服务器并开始创作。
{% codeblock "命令行" %} {% codeblock "命令行" %}
hexo s hexo server
{% endcodeblock %} {% endcodeblock %}
您可以继续阅读[Icarus用户指南](/hexo-theme-icarus/tags/Icarus用户指南/)系列文章来了解Icarus的使用与配置。 如需了解更多主题、挂件、和插件相关的信息，请查看
同时，您可以从Icarus的[`site`分支](https://github.com/ppoffice/hexo-theme-icarus/tree/site)上获取本网站的源码供您参考。 [Icarus用户指南](/hexo-theme-icarus/tags/Icarus用户指南/)。
你也可以参考本站的源代码来获取更多的使用示例。
本站源代码位于GitHub上Icarus代码仓库的[`site`分支](https://github.com/ppoffice/hexo-theme-icarus/tree/site)。
此外，你也可能在[Gitter](https://gitter.im/hexo-theme-icarus/)上获得其他Icarus用户的帮助。
**额外资源** **额外资源**
下面的一些资源可以帮助你进一步个性化你的站点。 下面是一些帮助你进一步个性化你的站点的其他资源。
你也可以[点击此处](https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/zh-CN/Getting-Started.md)来提交你的Icarus个性化配置教程。 你也可以[点击此处](https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/zh-CN/Getting-Started.md)来提交你的Icarus教程。
<div class="menu-list is-size-6"> <div class="menu-list is-size-6">
<a href="https://hexo.io/zh-cn/docs/index.html"><i class="fas fa-bookmark mr-2"></i> Hexo中文文档</a> <a href="https://hexo.io/zh-cn/docs/index.html"><i class="fas fa-bookmark mr-2"></i> Hexo中文文档</a>
@ -71,8 +82,10 @@ hexo s
<br> <br>
<div class="notification is-warning is-size-6"> <article class="message message-immersive is-warning">
文章内容有误？请点击<a href="https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/zh-CN/Getting-Started.md">此处</a>提交修改。 <div class="message-body">
<i class="fas fa-question-circle mr-2"></i>文章内容有误？点击<a href="https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/zh-CN/Getting-Started.md">此处</a>提交修改。
</div> </div>
</article>
<a style="background-color:black;color:white;text-decoration:none;padding:4px 6px;font-size:12px;line-height:1.2;display:inline-block;border-radius:3px" href="https://www.dpm.org.cn/collection/paint/228354.html" target="_blank" rel="noopener noreferrer"><span style="display:inline-block;padding:2px 3px"><svg xmlns="http://www.w3.org/2000/svg" style="height:12px;width:auto;position:relative;vertical-align:middle;top:-1px;fill:white" viewBox="0 0 32 32"><title>unsplash-logo</title><path d="M20.8 18.1c0 2.7-2.2 4.8-4.8 4.8s-4.8-2.1-4.8-4.8c0-2.7 2.2-4.8 4.8-4.8 2.7.1 4.8 2.2 4.8 4.8zm11.2-7.4v14.9c0 2.3-1.9 4.3-4.3 4.3h-23.4c-2.4 0-4.3-1.9-4.3-4.3v-15c0-2.3 1.9-4.3 4.3-4.3h3.7l.8-2.3c.4-1.1 1.7-2 2.9-2h8.6c1.2 0 2.5.9 2.9 2l.8 2.4h3.7c2.4 0 4.3 1.9 4.3 4.3zm-8.6 7.5c0-4.1-3.3-7.5-7.5-7.5-4.1 0-7.5 3.4-7.5 7.5s3.3 7.5 7.5 7.5c4.2-.1 7.5-3.4 7.5-7.5z"></path></svg></span><span style="display:inline-block;padding:2px 3px">王希孟 千里江山图卷</span></a> <a style="background-color:black;color:white;text-decoration:none;padding:4px 6px;font-size:12px;line-height:1.2;display:inline-block;border-radius:3px" href="https://www.dpm.org.cn/collection/paint/228354.html" target="_blank" rel="noopener noreferrer"><span style="display:inline-block;padding:2px 3px"><svg xmlns="http://www.w3.org/2000/svg" style="height:12px;width:auto;position:relative;vertical-align:middle;top:-1px;fill:white" viewBox="0 0 32 32"><title>unsplash-logo</title><path d="M20.8 18.1c0 2.7-2.2 4.8-4.8 4.8s-4.8-2.1-4.8-4.8c0-2.7 2.2-4.8 4.8-4.8 2.7.1 4.8 2.2 4.8 4.8zm11.2-7.4v14.9c0 2.3-1.9 4.3-4.3 4.3h-23.4c-2.4 0-4.3-1.9-4.3-4.3v-15c0-2.3 1.9-4.3 4.3-4.3h3.7l.8-2.3c.4-1.1 1.7-2 2.9-2h8.6c1.2 0 2.5.9 2.9 2l.8 2.4h3.7c2.4 0 4.3 1.9 4.3 4.3zm-8.6 7.5c0-4.1-3.3-7.5-7.5-7.5-4.1 0-7.5 3.4-7.5 7.5s3.3 7.5 7.5 7.5c4.2-.1 7.5-3.4 7.5-7.5z"></path></svg></span><span style="display:inline-block;padding:2px 3px">王希孟 千里江山图卷</span></a>