chore(doc): update en FAQ

pull/729/head
ppoffice 2020-05-02 01:52:15 -04:00
parent 371f6f824c
commit f3a04d1061
1 changed files with 116 additions and 70 deletions

View File

@ -4,34 +4,39 @@ thumbnail: /gallery/thumbnails/vector_landscape_3.svg
toc: true toc: true
--- ---
The article presents some of the frequently asked questions about Icarus and their solutions. The article answers some frequently asked questions about Icarus.
Please also read through the [Icarus User Guide](/hexo-theme-icarus/tags/Icarus-User-Guide/), If your question is not answered here, you can also refer to
[Hexo documentation](https://hexo.io/docs/index.html) and [Icarus User Guide](/hexo-theme-icarus/tags/Icarus-User-Guide/),
[Icarus GitHub Issues](https://github.com/ppoffice/hexo-theme-icarus/issues?q=) if you cannot find [Hexo documentation](https://hexo.io/docs/index.html), and
the answer to your question here. [GitHub Issues](https://github.com/ppoffice/hexo-theme-icarus/issues?q=).
Additionally, you may find help from other Icarus users on [Gitter](https://gitter.im/hexo-theme-icarus/).
<!-- more --> <!-- more -->
<div class="notification is-success is-size-6"> <article class="message message-immersive is-primary">
This article is also available in: <a href="{% post_path zh-CN/FAQ %}">简体中文</a>. <div class="message-body">
<i class="fas fa-lightbulb mr-2"></i>
This article is also available in <a href="{% post_path zh-CN/FAQ %}">简体中文</a>.
</div> </div>
</article>
## Site ## Site
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <div class="message-body">
My Hexo site is not generating./There are errors when generating my site. I can't generate my site. / I met some errors when I generate my site.
</div> </div>
</article> </article>
Icarus requires Node.js of version 8.3.0 and above, Hexo of version 4.2.0 and above, and some other Icarus 3 runs on Node.js 8.3.0 or a newer version.
package dependencies listed in the `peerDependencies` section of the It also requires Hexo 4.2.0 or a newer version.
Apart from that, make sure you have all the Node.js dependencies installed.
You can find them in the `peerDependencies` section of the
[`themes/icarus/package.json`](https://github.com/ppoffice/hexo-theme-icarus/blob/master/package.json) [`themes/icarus/package.json`](https://github.com/ppoffice/hexo-theme-icarus/blob/master/package.json)
file. file.
Please make sure you meet all the dependency requirements. Also, remove all unused Node.js dependencies from your site, or they may cause strange problems to
Also, it is possible that dependencies of the previous theme you used could interfere with Icarus. Icarus.
Please remove them before you switch to Icarus.
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <div class="message-body">
@ -39,44 +44,72 @@ How do I change the language of my site?
</div> </div>
</article> </article>
Edit your site's `_config.yml` under the root directory, change the following setting: Open the site configuration file `_config.yml` under the root directory.
Change the following setting:
{% codeblock _config.yml lang:diff %} {% codeblock _config.yml lang:diff %}
- language: en - language: en
+ language: <language_name> + language: <language_name>
{% endcodeblock %} {% endcodeblock %}
You can find available translations under the `themes/icarus/languages` directory. You can find all available translations under the `themes/icarus/languages` directory.
The file name without file extension is the language name used in `_config.yml`. The `language_name` is the translation file name without the `.yml` extension.
## Layout ## Layout
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <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? How do I change the page width? How do I use the one/two/three-column layout?
</div> </div>
</article> </article>
To change the width of the page, you need to edit the style file located at `themes/icarus/include/style/responsive.styl`. To change the page width, edit the style file `themes/icarus/include/style/responsive.styl`.
This file defines the container width under different screen sizes. It 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 refer to the [Bulma documentation](https://bulma.io/documentation/columns/sizes/) for more details on the To change the width of the widgets or main content, edit `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` in these files.
The number in the class names marks the column size a column takes.
The screen size after the number, such as `tablet` and `widescreen`, refers to the condition when the column
sizes take effect.
Change the number in the class names such that the column size of main column and widget column(s) add up to
12 under the same screen size.
For example, to have the main content column wider on `widescreen`, you can make the following changes:
{% codeblock themes/icarus/layout/layout.jsx lang:diff >folded %}
<div class={classname({
column: true,
'order-2': true,
'column-main': true,
'is-12': columnCount === 1,
- 'is-8-tablet is-8-desktop is-8-widescreen': columnCount === 2,
+ 'is-8-tablet is-8-desktop is-9-widescreen': columnCount === 2,
'is-8-tablet is-8-desktop is-6-widescreen': columnCount === 3
{% endcodeblock %}
{% codeblock themes/icarus/layout/common/widgets.jsx lang:diff >folded %}
function getColumnSizeClass(columnCount) {
switch (columnCount) {
case 2:
- return 'is-4-tablet is-4-desktop is-4-widescreen';
+ return 'is-4-tablet is-4-desktop is-3-widescreen';
case 3:
return 'is-4-tablet is-4-desktop is-3-widescreen';
{% endcodeblock %}
You can refer to [Bulma documentation](https://bulma.io/documentation/columns/sizes/) for more details on the
column system. column system.
Please make sure the number in the class names 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`.
You can create a one-column layout by removing all widgets from your theme configurations. Here are some tips for creating a one/two/three-column layout:
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.
To change the layout in certain posts or pages, please refer to the - You can remove all widgets from your theme configurations to create a one-column layout.
[Icarus User Guide - Configuring the Theme](/hexo-theme-icarus/Configuration/icarus-user-guide-configuring-the-theme/#Additional-Configuration-Files-and-Priority). - You can move all your widgets to the same side of the page to create a two-column layout.
- You can place widgets on both sides of the page to create a three-column layout.
To change the layout for a single or all posts/pages, refer to
[Configuration Files and Priority](/hexo-theme-icarus/Configuration/icarus-user-guide-configuring-the-theme/#Configuration-Files-and-Priority).
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <div class="message-body">
@ -84,56 +117,65 @@ Where are the layout files for widgets/comments/share...? How do I customize bui
</div> </div>
</article> </article>
The layout files for comment plugins, donate buttons, site search, share buttons, widgets, and some other plugins The layout files for plugins and widgets have been moved to a separate Node.js package called
have been moved to a separate Node.js package called [`hexo-component-inferno`](https://github.com/ppoffice/hexo-component-inferno). [`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 This help theme developers better reuse common components across different themes and make overriding these
override these built-in components easily. components easy for average users.
To customize these components, you may copy the layout files from the `hexo-component-inferno` repository and place To customize these components, copy the layout files from the `hexo-component-inferno` repository and place
them in the corresponding directories under the Icarus layout directory. them in the corresponding directories under `themes/icarus/layout`.
For example, if you want to customize the Valine comment plugin, you can copy 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) [`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. from the `hexo-component-inferno` repository to `themes/icarus/layout/comment/valine.jsx`.
Then, fix some of the Node.js imports in the head of the file. Also, remember to fix Node.js imports like the following:
{% codeblock themes/icarus/layout/comment/valine.jsx lang:diff %} {% codeblock themes/icarus/layout/comment/valine.jsx lang:diff %}
- const { cacheComponent } = require('../../util/cache'); - const { cacheComponent } = require('../../util/cache');
+ const { cacheComponent } = require('hexo-component-inferno/lib/util/cache'); + const { cacheComponent } = require('hexo-component-inferno/lib/util/cache');
{% endcodeblock %} {% endcodeblock %}
After that, `hexo clean` your site and regenerate the HTML files. Finally, `hexo clean` your site before regenerating the HTML.
Similarly, you can override built-in static files by copying them from the `hexo-component-inferno` repository and Similarly, you can override static files like
place them to the corresponding directory under `themes/icarus/source`. [`asset/js/insight.js`](https://github.com/ppoffice/hexo-component-inferno/blob/0.2.4/asset/js/insight.js)
in the same way.
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <div class="message-body">
I changed something in the layout files. Why don't my layout changes take effect when I refresh the page (assuming I am running the
But why didn't the changes take effect when I refresh the page (when using <code>hexo server</code>)/when I <code>hexo generate</code>? <code>hexo server</code>?
</div> </div>
</article> </article>
The layout files are cached when you start a local Hexo server with `hexo server`. Icarus caches the layout files when you start the local Hexo server with the `hexo server` command.
Other times some intermediate data is cached in the `db.json` or memory. To make the layout changes take effect, restart the local server.
Please use `hexo clean` before `hexo server` or `hexo generate`.
Other times some intermediate data may be cached by Hexo in the memory or `db.json` database.
Execute `hexo clean` before running `hexo server` or `hexo generate` should resolve this issue.
## Content ## Content
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <div class="message-body">
My logo/images are not showing up./My images only shows in index pages but not posts. My images are not showing up. / My images only show in index pages but not in posts.
</div> </div>
</article> </article>
Please make sure you use the absolute paths of your images. Make sure you use the absolute paths to your images.
For example, if you put your images under `source/gallery/`, and your site is in a For example, your site is in a subdirectory of your domain name like
subdirectory of your domain name like `https://ppoffice.github.io/hexo-theme-icarus`, `https://ppoffice.github.io/hexo-theme-icarus` and you `image.jpg` under `source/gallery/`.
you should include your image like this: `/hexo-theme-icarus/gallery/<file_name>.<file_extension>`. You should include your image like this: `/hexo-theme-icarus/gallery/image.jpg`.
You can also use the Hexo `{% img %}` tag to omit the subdirectory part of your image path: You can also use Hexo's <code>{% raw %}{% img %}{% endraw %}</code> tag like the following to include an
<code>&#123;% img /gallery/&lt;file_name&gt;.&lt;file_extension&gt; ... %}</code>. image automatically:
Please refer to the [Hexo documentation](https://hexo.io/docs/tag-plugins#Image) for more details.
```
{% img /gallery/image.jpg "Image title" %}
```
In this case, you may omit the subdirectory of your domain name.
You can refer to [Hexo documentation](https://hexo.io/docs/tag-plugins#Image) for more details.
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <div class="message-body">
@ -141,9 +183,11 @@ How to add an excerpt for a post? How to display the "Read more" button?
</div> </div>
</article> </article>
Add `<!-- more -->` tag in your post. Put a `<!-- 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. Post content before this tag will be marked as an excerpt.
You may also add custom excerpt by specifying it in the post's front-matter. Content after this tag will not show up on index pages.
You can also specify a custom excerpt in the post's front-matter.
{% codeblock some-post.md lang:yaml %} {% codeblock some-post.md lang:yaml %}
title: Some Post title: Some Post
@ -159,31 +203,30 @@ How do I encrypt my posts?
</div> </div>
</article> </article>
Please use third-party Hexo plugins like [hexo-blog-encrypt](https://github.com/MikeCoder/hexo-blog-encrypt). Use third-party Hexo plugins such as [hexo-blog-encrypt](https://github.com/MikeCoder/hexo-blog-encrypt).
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <div class="message-body">
How do I use fancy elements and styling in my posts just like this one? How do I use those fancy elements in this article for my posts?
</div> </div>
</article> </article>
You can use raw HTML in your Markdown files. Refer to [Bulma documentation](https://bulma.io/documentation/) for all available elements and styles.
Please refer to the [Bulma documentation](https://bulma.io/documentation/) for more details on available Copy the HTML snippets and put them in your Markdown files directly.
elements and styles.
## Widgets and Plugins ## Widgets and Plugins
<article class="message is-primary" style="font-size:1em"> <article class="message is-primary" style="font-size:1em">
<div class="message-body"> <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 those red alerts that are showing on the page and warning me of configuration value not set?
How can I get rid of them?
</div> </div>
</article> </article>
If you don't want to enable some plugins/widgets, you can simply delete them or comment them out in the Those alerts usually show up when you miss out on some plugin or widget configurations.
configurations. If you don't want to enable a certain plugin or widget, delete it or comment it out from your theme configurations.
For example, if you don't want to enable any comment plugin, just comment these lines:
For example, you can disable the comment plugins by commenting out the following lines:
{% codeblock themes/icarus/_config.yml lang:diff %} {% codeblock themes/icarus/_config.yml lang:diff %}
- comment: - comment:
@ -195,9 +238,12 @@ For example, if you don't want to enable any comment plugin, just comment these
{% endcodeblock %} {% endcodeblock %}
<div class="notification is-warning is-size-6"> <article class="message message-immersive is-warning">
<div class="message-body">
<i class="fas fa-exclamation-triangle mr-2"></i>
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. 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> </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-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> <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>