FAQ

The article answers some frequently asked questions about Icarus. If your question is not answered here, you can also refer to Icarus User Guide, Hexo documentation, and GitHub Issues. Additionally, you may find help from other Icarus users on GitHub Discussions.

This article is also available in 简体中文.

Site

I can't generate my site. / I met some errors when I generate my site.

Icarus 7 runs on Node.js 14.0 or a newer version. It also requires Hexo 7.1.1 or a newer version (Hexo 8 is supported since Icarus 6.2.0, and it requires Node.js 20.19.0 or a newer version). Apart from that, make sure you have all the Node.js dependencies installed. You can find them in the dependencies section of the <icarus_directory>/package.json file. If you installed Icarus from source, install them in the root directory of your site, as described in

Getting Started with Icarus.

In any case, hexo-renderer-inferno must be listed in the package.json of your site, because Hexo only loads the plugins listed there; without it, Hexo cannot render the layouts of Icarus. Also, remove all unused Node.js dependencies from your site, or they may cause strange problems to Icarus.

How do I change the language of my site?

Open the site configuration file _config.yml under the root directory. Change the following setting:

_config.yml

- language: en
+ language: <language_name>

You can find all available translations under the <icarus_directory>/languages directory. The <language_name> is the translation file name without the .yml extension. If there is no translation for your language, Icarus falls back to English. To change the language of a single post, see Post Language.

Layout

How do I change the page width? How do I use the one/two/three-column layout?

To change the page width, edit the style file <icarus_directory>/include/style/responsive.styl. It defines the container width under different screen sizes.

To change the width of the widgets or main content, edit <icarus_directory>/layout/common/widgets.jsx and <icarus_directory>/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 number of columns a widget or main content 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 count 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:

<icarus_directory>/layout/layout.jsx >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

<icarus_directory>/layout/common/widgets.jsx >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';

You can refer to Bulma documentation for more details on the column system.

Here are some tips for creating a one/two/three-column layout:

• You can remove all widgets from your theme configurations, or set widgets to null, to create a one-column layout.
• 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.

Note that the table of contents widget only shows on posts and pages with toc: true (set in their front-matter or in a configuration file). A sidebar that only has the table of contents widget does not take up a column on other pages.

To change the layout for a single or all posts/pages, refer to Configuration Files and Priority.

Where are the layout files for widgets/comments/share...? How do I customize built-in widgets/comments/share...?

The layout files for plugins and widgets have been moved to a separate Node.js package called hexo-component-inferno. This helps theme developers better reuse common components across different themes and makes overriding these components easy for average users.

To customize these components, copy the layout files from the hexo-component-inferno repository and place them in the corresponding directories under <icarus_directory>/layout. For example, if you want to customize the Waline comment plugin, you can copy src/view/comment/waline.jsx from the hexo-component-inferno repository to <icarus_directory>/layout/comment/waline.jsx. Copy the file from the release you have installed (see the version in node_modules/hexo-component-inferno/package.json), as the latest code in the repository may need a newer release. Also, remember to change the relative imports of ../../util/... to hexo-component-inferno/lib/util/..., like the following:

<icarus_directory>/layout/comment/waline.jsx

- const { cacheComponent } = require('../../util/cache');
+ const { cacheComponent } = require('hexo-component-inferno/lib/util/cache');

Finally, hexo clean your site before regenerating the HTML.

Similarly, you can override static files like asset/js/insight.js by putting your own copy at the same path under the theme’s source directory, e.g., <icarus_directory>/source/js/insight.js.

If you installed Icarus via NPM, <icarus_directory> is node_modules/hexo-theme-icarus, and upgrading or reinstalling Icarus overwrites your changes there. To keep customizing the theme's files, install Icarus from source instead (see Getting Started with Icarus and Upgrade Guide).

Why don't my layout changes take effect when I refresh the page (assuming I am running hexo server)?

Icarus caches the layout files when you start the local Hexo server with the hexo server command. To make the layout changes take effect, restart the local server.

Other times some intermediate data may be cached by Hexo in the memory or db.json database. Running hexo clean before hexo server or hexo generate should resolve this issue.

Content

My images are not showing up. / My images only show in index pages but not in posts.

Make sure you use the absolute paths (starting with /) to your images. For example, your site is in a subdirectory of your domain name like https://ppoffice.github.io/hexo-theme-icarus (i.e., root: /hexo-theme-icarus/ in your site configuration _config.yml) and your image image.jpg is under source/gallery/. In Markdown, include your image without the subdirectory, like this: ![Image title](/gallery/image.jpg). The Markdown renderer (hexo-renderer-marked, with its default prependRoot: true) adds the root to image paths for you, so writing the subdirectory yourself would make it appear twice. HTML <img> tags, on the other hand, are left as they are, so you need to include the subdirectory yourself: <img src="/hexo-theme-icarus/gallery/image.jpg">.

You can also use Hexo’s {% img %} tag like the following to include an image automatically:

{% img /gallery/image.jpg "Image title" %}

In this case, you may omit the subdirectory from your image path as well. You can refer to Hexo documentation for more details.

How to add an excerpt for a post? How to display the "Read more" button?

Put a <!-- more --> tag in your post. Post content before this tag will be marked as an excerpt. Content after this tag will not show up on index pages.

You can also specify a custom excerpt in the post’s front-matter.

some-post.md

title: Some Post
date: 2020-01-01
excerpt: This is an article about ...
---
# Post content...

How do I encrypt my posts?

Use third-party Hexo plugins such as hexo-blog-encrypt.

How do I use those fancy elements in this article for my posts?

Refer to Bulma documentation for all available elements and styles. Copy the HTML snippets and put them in your Markdown files directly.

Widgets and Plugins

How can I get rid of those red alerts that are showing on the page and warning me of configuration value not set?

Those alerts usually show up when you miss out on some plugin or widget configurations. For example, the _config.icarus.yml that Icarus generates on the first run enables a comment plugin, donation buttons, share buttons, and several widgets (such as AdSense and follow.it) with empty placeholder values. Fill in the values of the ones you want to use. If you don’t want to enable a certain plugin or widget, delete it or comment it out from your theme configurations.

For example, you can disable the comment plugins by commenting out the following lines:

_config.icarus.yml

- comment:
-     type: disqus
-     shortname: 
+ # comment:
+ #     type: disqus
+ #     shortname: 

To disable a plugin for a single post, see Post/Page Front-matter.

Something wrong with this article? Click here to submit your revision.