chore(doc): update docs

pull/701/head
ppoffice 2020-04-20 23:23:26 -04:00
parent 3c542f991d
commit 2cb030d31c
8 changed files with 272 additions and 42 deletions

View File

@ -200,7 +200,7 @@ Inserts an image with specified size.
{% img [class names] /path/to/image [width] [height] [title text [alt text]] %}
```
{% img /gallery/thumbnails/desert.jpg 100% 100% '"Desert" "Desert"' %}
{% img /gallery/thumbnails/vector_landscape_1.svg 100% 100% '"Vector Landscape" "Vector Landscape"' %}
## Link

View File

@ -13,9 +13,8 @@ toc: true
Icarus' default theme configuration file `_config.yml` resides in the `themes/icarus` directory.
It defines the global layout and style settings of the theme as well as external features such as comment
plugins and widgets.
In this post, we will be covering settings that relate to the styling and overall layout of your site.
We will be covering the mechanisms used by Icarus to configure your site and going through the format and meaning of some configuration
settings.
In this post, we will cover the mechanisms used by Icarus to configure your site and going through the format
and meaning of some configuration settings.
<!-- more -->

View File

@ -1,54 +1,203 @@
title: FAQ
date: 2020-02-01
thumbnail: /gallery/thumbnails/vector_landscape_3.svg
toc: true
---
### How do I put text instead of an image as my site's logo?
The article presents some of the frequently asked questions about Icarus and their solutions.
Please also read through the [Icarus User Guide](/hexo-theme-icarus/tags/Icarus-User-Guide/),
[Hexo documentation](https://hexo.io/docs/index.html) and
[Icarus GitHub Issues](https://github.com/ppoffice/hexo-theme-icarus/issues?q=) if you cannot find
the answer to your question here.
If you consider using a piece of text instead of an image as the logo of your site, you can do something like this:
{% codeblock lang:yaml _config.yml %}
logo:
text: My Beautiful Site
{% endcodeblock %}
<!-- more -->
### How do I change the site's language?
Edit your blog's `_config.yml`(not your theme's), change the following field:
```diff
<!-- <div class="notification is-success is-size-6">
This article is also available in: <a href="{% post_path zh-CN/FAQ %}">简体中文</a>.
</div> -->
## Site
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
My Hexo site is not generating./There are errors when generating my site.
</div>
</article>
Icarus requires Node.js of version 8.3.0 and above, Hexo of version 4.2.0 and above, and some other
package dependencies listed in the `peerDependencies` section of the
[`themes/icarus/package.json`](https://github.com/ppoffice/hexo-theme-icarus/blob/master/package.json)
file.
Please make sure you meet all the dependency requirements.
Also, it is possible that dependencies of the previous theme you used could interfere with Icarus.
Please remove them before you switch to Icarus.
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
How do I change the language of my site?
</div>
</article>
Edit your site's `_config.yml` under the root directory, change the following setting:
{% codeblock _config.yml lang:diff %}
- language: en
+ language: zh-CN
```
+ language: <language_name>
{% endcodeblock %}
You can find available translations under `icarus/languages` folder.
You can find available translations under the `themes/icarus/languages` directory.
The file name without file extension is the language name used in `_config.yml`.
### How to add an excerpt for a post? How to display the "Read more" button?
Add `<!-- more -->` tag in your post. Post content before this tag will be marked as an excerpt and content after this tag will not show on the index page.
### Why aren't my changes deployed to the Github Pages?
Please run these commands before `hexo deploy`:
## Layout
```bash
$ hexo clean
$ rm -r .deploy_git
```
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
How do I change the width of the page? How do I use a one/two/three-column layout in certain posts/pages?
</div>
</article>
### How to add meta tags for a specified post/page?
To change the width of the page, you need to edit the style file located at `themes/icarus/include/style/responsive.styl`.
This file defines the container width under different screen sizes.
If you also want to change the column width of the widgets or the main content, please go to `themes/icarus/layout/common/widgets.jsx` and `themes/icarus/layout/layout.jsx`.
Find the CSS class names like `is-12`, `is-8-tablet`, and `is-4-widescreen`.
Change the number in these class names to the one you want.
You can add meta tags for each post/page through front-matter:
You can refer to the [Bulma documentation](https://bulma.io/documentation/columns/sizes/) for more details on the
column system.
Please make sure the number of widget columns and the main content column add up to 12 under the same screen size.
For example, if you change the width of the widget column to `is-3-widescreen` and you only have one widget column,
you need to make sure your main content column has a `is-9-widescreen`.
```diff
title: test post
date: 2015-01-26 21:55:37
tags:
comments: false
+ meta:
+ - name="robots";content="noindex, follow"
+ - name="another-meta";value="hello world";enabled=false
```
You can create a one-column layout by removing all widgets from your theme configurations.
To use a two-column layout, please move all your widgets to the same side of the page by setting their `position`
to `left` or `right`.
The three-column layout can be achieved by placing widgets on both sides of the page.
### Does this theme support RTL(Right-to-Left) language?
To change the layout in certain posts or pages, please refer to the
[Icarus User Guide - Configuring the Theme](/hexo-theme-icarus/Configuration/icarus-user-guide-configuring-the-theme/#Additional-Configuration-Files-and-Priority).
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
Where are the layout files for widgets/comments/share...? How do I customize built-in widgets/comments/share...?
</div>
</article>
The layout files for comment plugins, donate buttons, site search, share buttons, widgets, and some other plugins
have been moved to a separate Node.js package called [`hexo-component-inferno`](https://github.com/ppoffice/hexo-component-inferno).
In doing this, the theme developers can better reuse common components across different themes and allow users to
override these built-in components easily.
To customize these components, you may copy the layout files from the `hexo-component-inferno` repository and place
them in the corresponding directories under the Icarus layout directory.
For example, if you want to customize the Valine comment plugin, you can copy
[`src/view/comment/valine.jsx`](https://github.com/ppoffice/hexo-component-inferno/blob/0.2.4/src/view/comment/valine.jsx)
from the `hexo-component-inferno` repository and place it in the `themes/icarus/layout/comment` directory.
Then, fix some of the Node.js imports in the head of the file.
{% codeblock themes/icarus/layout/comment/valine.jsx lang:diff %}
- const { cacheComponent } = require('../../util/cache');
+ const { cacheComponent } = require('hexo-component-inferno/lib/util/cache');
{% endcodeblock %}
After that, `hexo clean` your site and regenerate the HTML files.
Similarly, you can override static files by copying them from the `hexo-component-inferno` repository and place them
to the corresponding directory under `themes/icarus/source`.
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
I changed something in the layout files.
But why didn't the changes take effect when I refresh the page (when using <code>hexo s</code>)/when I <code>hexo generate</code>?
</div>
</article>
The layout files are cached when you start a local Hexo server with `hexo server`.
Other times some intermediate data is cached in the `db.json` or memory.
Please use `hexo clean` before `hexo server` or `hexo generate`.
## Content
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
My logo/images are not showing up./My images only shows in index pages but not posts.
</div>
</article>
Please make sure you use the absolute paths of your images.
For example, if you put your images under `source/gallery/`, and your site is in a
subdirectory of your domain name like `https://ppoffice.github.io/hexo-theme-icarus`,
you should include your image like this: `/hexo-theme-icarus/gallery/<file_name>.<file_extension>`.
You can also use the Hexo `{% img %}` tag to omit the subdirectory part of your image path:
<code>&#123;% img /gallery/&lt;file_name&gt;.&lt;file_extension&gt; ... %}</code>.
Please refer to the [Hexo documentation](https://hexo.io/docs/tag-plugins#Image) for more details.
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
How to add an excerpt for a post? How to display the "Read more" button?
</div>
</article>
Add `<!-- more -->` tag in your post.
Post content before this tag will be marked as an excerpt and content after this tag will not show on the index page.
You may also add custom excerpt by specifying it in the post's front-matter.
{% codeblock some-post.md lang:yaml %}
title: Some Post
date: 2020-01-01
excerpt: This is an article about ...
---
# Post content...
{% endcodeblock %}
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
How do I encrypt my posts?
</div>
</article>
Please use third-party Hexo plugins like [hexo-blog-encrypt](https://github.com/MikeCoder/hexo-blog-encrypt).
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
How do I use fancy elements and styling in my posts just like this one?
</div>
</article>
You can use raw HTML in your Markdown posts.
Please refer to the [Bulma documentation](https://bulma.io/documentation/) for more details on available
elements and styles.
## Widgets and Plugins
<article class="message is-primary" style="font-size:1em">
<div class="message-body">
My page is showing red alerts, saying that some settings are not set for a plugin/widget.
How can I get rid of them?
</div>
</article>
If you don't want to enable some plugins/widgets, you can simply delete them or comment them out in the
configurations.
For example, if you don't want to enable any comment plugin, just delete these lines:
{% codeblock themes/icarus/_config.yml lang:diff %}
- comment:
- type: disqus
- shortname:
+ # comment:
+ # type: disqus
+ # shortname:
{% endcodeblock %}
<div class="notification is-warning is-size-6">
Something wrong with this article? Click <a href="https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/en/FAQ.md">here</a> to submit your revision.
</div>
Partially yes. Please refer to [Issues#234](https://github.com/ppoffice/hexo-theme-icarus/issues/234)
<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-landscapee" 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>

View File

@ -7,7 +7,7 @@ tags:
language: en
---
Icarus is a simple, delicate, and modern theme for the static site generator Hexo.
It allows you to set up a single or multiple-column (up to three column) blog with its versatile layout configuration.
It allows you to set up a single or multiple-column (up to three columns) blog with its versatile layout configuration.
Additionally, it offers plentiful plugins and pluggable widgets so that you can enable the features you want in no time.
And with the all-new API designing, Icarus makes the development of this theme painless for developers and users.
@ -26,7 +26,7 @@ git clone https://github.com/ppoffice/hexo-theme-icarus.git themes/icarus -b <ve
{% endcodeblock %}
You may omit the `-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 history if Icarus as well.
You may also leave `--depth 1` out if you want to download full Git history of Icarus as well.
Furthermore, you can install Icarus as a Git submodule by executing the following command:
{% codeblock "Git Bash/Shell" %}
@ -56,10 +56,19 @@ about Icarus and its configuration.
Also, you can refer to the source code of this site for more examples by fetching the
[`site` branch](https://github.com/ppoffice/hexo-theme-icarus/tree/site) of Icarus from GitHub.
**Additional Resources**
The following are some additional resources that can help you take a step further into customizing your site.
You can also add a link to your Icarus tutorial below by click [this link](https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/en/Getting-Started.md).
<div class="menu-list is-size-6">
<a href="https://hexo.io/docs/index.html"><i class="fas fa-bookmark mr-2"></i> Hexo documentation</a>
</div>
<br>
<div class="notification is-warning is-size-6">
Something wrong with this article? Click <a href="https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/en/Getting-Started.md">here</a> to submit your revision.
</div>
<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>

View File

@ -120,6 +120,33 @@ This is another block expression:
\\[f(x) = \int_{-\infty}^\infty\hat f(\xi)e^{2 \pi i \xi x}d\xi\\]
{% endcodeblock %}
Sometimes your \\(\TeX\\) syntax will be mistaken as Markdown syntax, which will result in rendering error.
For instance, the following equation will not work since it contains more than one `_` (underscores),
which are mistaken for the italic text when processed by the Markdown renderer:
{% codeblock Some-Post.md lang:tex %}
$$
\hat{x}_{k}=\hat{x}_{k}^{-}+K_{t}\left(y_{k}\right)
$$
{% endcodeblock %}
In this case, you can either escape every character that may cause confusion:
{% codeblock Some-Post.md lang:tex %}
$$
\hat{x}\_{k}=\hat{x}\_{k}^{-}+K\_{t}\left(y\_{k}\right)
$$
{% endcodeblock %}
or simply wrap the whole equation with an additional HTML tag:
{% codeblock Some-Post.md lang:tex %}
<div>
$$
\hat{x}_{k}=\hat{x}_{k}^{-}+K_{t}\left(y_{k}\right)
$$
</div>
{% endcodeblock %}
## MathJax
@ -222,6 +249,9 @@ Expressions should be wrapped in <code>\\`</code> in this case.
When \`a != 0\`, there are two solutions to \`ax^2 + bx + c = 0\` and they are <p style="text-align:center">\`x = (-b +- sqrt(b^2-4ac))/(2a)\`.</p>
{% endcodeblock %}
Sometimes your latex syntax will be mistaken as Markdown syntax, which will result in rendering error.
Please refer to the [KaTeX](#KaTeX) section for solutions to this.
**Preview(\\(\TeX\\) & \\(\LaTeX\\))**
This is an inline expression: \\(ax^2+bx+c=0\\). This is another inline expression: $ax^2+bx+c>0$.

View File

@ -68,7 +68,7 @@ WARN [
- 文章/页面的[front-matter](https://hexo.io/docs/front-matter.html)
- 根目录下的站点配置文件`_config.yml`
`_config.post.yml`和`_config.page.yml`配置文件与默认配置文件的格式和定义想吐
`_config.post.yml`和`_config.page.yml`配置文件与默认配置文件的格式和定义相同
你可以在`_config.post.yml`中设置仅对文章页面生效的配置,而这些配置将覆盖默认配置文件中的同名配置。
例如,你可以在此配置文件中把所有的挂件放置在页面左侧,从而将所有的文章页面设置为两栏布局,同时其他页面仍保持三栏布局:

View File

@ -57,6 +57,19 @@ hexo s
您可以继续阅读[Icarus用户指南](/hexo-theme-icarus/tags/Icarus用户指南/)系列文章来了解Icarus的使用与配置。
同时您可以从Icarus的[`site`分支](https://github.com/ppoffice/hexo-theme-icarus/tree/site)上获取本网站的源码供您参考。
**额外资源**
下面的一些资源可以帮助你进一步个性化你的站点。
你也可以[点击此处](https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/en/Getting-Started.md)来提交你的Icarus个性化配置教程。
<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://removeif.github.io/theme/%E5%8D%9A%E5%AE%A2%E6%BA%90%E7%A0%81%E5%88%86%E4%BA%AB.html"><i class="fas fa-bookmark mr-2"></i> 博客源码分享 by 辣椒の酱</a>
<a href="https://www.imaegoo.com/2020/icarus-3-guide/"><i class="fas fa-bookmark mr-2"></i> hexo-theme-icarus 3 食用经验分享 by iMaeGoo</a>
</div>
<br>
<div class="notification is-warning is-size-6">
文章内容有误?请点击<a href="https://github.com/ppoffice/hexo-theme-icarus/edit/site/source/_posts/zh-CN/Getting-Started.md">此处</a>提交修改。
</div>

View File

@ -116,6 +116,33 @@ $$\displaystyle \frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}}
\\[f(x) = \int_{-\infty}^\infty\hat f(\xi)e^{2 \pi i \xi x}d\xi\\]
{% endcodeblock %}
有时你的\\(\TeX\\)语法会被错认为Markdown语法而导致公式渲染异常。
例如,下面的公式不会渲染成功,因为其中包含多个`_`(下划线)而被Markdown渲染器错误的认成Markdown的斜体字语法。
{% codeblock Some-Post.md lang:tex %}
$$
\hat{x}_{k}=\hat{x}_{k}^{-}+K_{t}\left(y_{k}\right)
$$
{% endcodeblock %}
在这种情况下,你可以选择转义每个可能导致歧义的字符:
{% codeblock Some-Post.md lang:tex %}
$$
\hat{x}\_{k}=\hat{x}\_{k}^{-}+K\_{t}\left(y\_{k}\right)
$$
{% endcodeblock %}
或是简单的将整个公式用一个HTML标签包裹起来
{% codeblock Some-Post.md lang:tex %}
<div>
$$
\hat{x}_{k}=\hat{x}_{k}^{-}+K_{t}\left(y_{k}\right)
$$
</div>
{% endcodeblock %}
## MathJax
@ -212,6 +239,9 @@ A =
当\`a != 0\`,方程\`ax^2 + bx + c = 0\`有两个解,它们是<p style="text-align:center">\`x = (-b +- sqrt(b^2-4ac))/(2a)\`.</p>
{% endcodeblock %}
有时你的\\(\TeX\\)语法会被错认为Markdown语法而导致公式渲染异常。
请参照[KaTeX](#KaTeX)一节来解决此问题。
**效果预览(\\(\TeX\\) & \\(\LaTeX\\))**
这是一个行内公式:\\(ax^2+bx+c=0\\)。这是另一个行内公式:$ax^2+bx+c>0$。