Icarus User Guide - Configuring the Theme

Icarus User Guide - Configuring the Theme

Icarus’ default theme configuration file is _config.icarus.yml. It defines the global layout and style settings of the theme and controls external features such as plugins and widgets. This article details the general configurations of the theme. It also explains what configuration files are used and how Icarus generate and validate these configurations.

General Theme Configurations

Configuration Version

This version code is related to and but not always the same as the theme version code. Icarus uses it to determine whether to upgrade the default theme configuration file. You should not change it by yourself.

_config.icarus.yml
1
version: 4.0.0

Theme Variant

Choose a skin for Icarus. "default" and "cyberpunk" are supported values currently. You can take a look at the Cyberpunk variant here.

_config.icarus.yml
1
variant: default

Set the logo of your site. It will display on the navigation bar and the footer. The value of the logo can either be the path or URL to your logo image:

_config.icarus.yml
1
logo: /img/logo.svg

or text if you set it like the following:

_config.icarus.yml
1
2
logo:
text: My Beautiful Site

Favicon

You can specify the path or URL to your site’s favicon in the head section.

_config.icarus.yml
1
2
head:
favicon: /img/favicon.svg

Web App Manifest

Icarus supports basic PWA manifest.json generation and meta tags. To enable web app manifest, use the following configuration in your theme configuration file. You can also refer to MDN for details on each manifest configuration setting.

_config.icarus.yml >folded
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
manifest:
# Name of the web application (default to the site title)
name: Icaurs - Hexo Theme
# The displayed name of the web application
# when there is not enough space to display full name
short_name: Icarus
# The start URL of the web application
start_url: https://ppoffice.github.io/
# The default theme color for the application
theme_color: "#3273dc"
# A placeholder background color for the application page to display
# before its stylesheet is loaded
background_color: "#3273dc"
# The preferred display mode for the website
display: standalone
# Image files that can serve as application icons for different contexts
icons:
-
# The path to the image file
src: icons/touch-icon-iphone.png
# A string containing space-separated image dimensions
sizes: 144x144
# A hint as to the media type of the image (optional)
type: image/png
-
src: icons/touch-icon-ipad.png
sizes: 152x152
-
src: icon/logo.ico
sizes: 72x72 96x96 128x128 256x256

Open Graph

You can set up Open Graph in the head section. You should leave most of the settings blank in the configuration file. Only set those settings in the front-matter of your post if you need them. Please refer to Hexo documentation for details on each setting.

_config.icarus.yml >folded
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
head:
open_graph:
# Page title (og:title) (optional)
# You should leave this blank for most of the time
title:
# Page type (og:type) (optional)
# You should leave this blank for most of the time
type: blog
# Page URL (og:url) (optional)
# You should leave this blank for most of the time
url:
# Page cover (og:image) (optional)
# You should leave this blank for most of the time
image:
# Site name (og:site_name) (optional)
# You should leave this blank for most of the time
site_name:
# Page author (article:author) (optional)
# You should leave this blank for most of the time
author:
# Page description (og:description) (optional)
# You should leave this blank for most of the time
description:
# Twitter card type (twitter:card)
twitter_card:
# Twitter ID (twitter:creator)
twitter_id:
# Twitter Site (twitter:site)
twitter_site:
# Google+ profile link (deprecated)
google_plus:
# Facebook admin ID
fb_admins:
# Facebook App ID
fb_app_id:

Google Structured Data

You can set up Google Structured Data in the head section. You should leave most of the settings blank in the configuration file. Only set those settings in the front-matter of your post if you need them. Please refer to Search for Developers for details on each setting.

_config.icarus.yml >folded
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
head:
structured_data:
# Page title (optional)
# You should leave this blank for most of the time
title:
# Page description (optional)
# You should leave this blank for most of the time
description:
# Page URL (optional)
# You should leave this blank for most of the time
url:
# Page author (article:author) (optional)
# You should leave this blank for most of the time
author:
# Page images (optional)
# You should leave this blank for most of the time
image:

Page Metadata

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. 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. Separate the <field_name>=<field_value> pairs with ; if the <meta> tag has multiple fields and values.

_config.icarus.yml
1
2
3
4
head:
meta:
- 'name=theme-color;content=#123456'
- 'name=generator;content="Hexo 4.2.0"'

RSS

You can add a link to your RSS feed at the rss setting in the head section.

_config.icarus.yml
1
2
head:
rss: /path/to/atom.xml

The navbar section defines the menu items and links in the navigation bar. You may put any menu item in the navigation bar by adding <link_name>: <link_url> to the menu setting. To put links on the right side of the navigation bar, add <link_name>: <link_url> to the links setting.

_config.icarus.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
navbar:
# Naviagtion menu items
menu:
Home: /
Archives: /archives
Categories: /categories
Tags: /tags
About: /about
# Links to be shown on the right of the navigation bar
links:
GitHub: 'https://github.com'
Download on GitHub:
icon: fab fa-github
url: 'https://github.com/ppoffice/hexo-theme-icarus'

You can display a FontAwesome icon instead of text-only link with the following format:

Link format
1
2
3
<link_name>:
icon: <fontawesome_icon_class_name>
url: <link_url>

The footer section defines the links on the right side of the page footer. The link format is exactly the same as links in the navbar section.

_config.icarus.yml
1
2
3
4
5
6
7
8
9
10
11
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'

Code Highlight

If you have enabled code highlighting in Hexo, you can customize the code blocks with highlight settings in the article section. Choose a theme from all themes listed under highlight.js/src/styles. Then, copy the file name (without the .css extension) to the theme setting.

To hide the “copy” button of every code block, set clipboard to false. If you wish to fold or unfold all code blocks, set the fold setting to "folded" or "unfolded". You can also disable the folding feature by leaving the fold setting empty.

_config.icarus.yml
1
2
3
4
5
6
7
8
9
article:
highlight:
# Code highlight themes
# https://github.com/highlightjs/highlight.js/tree/master/src/styles
theme: atom-one-light
# Show copy code button
clipboard: true
# Default folding status of the code blocks. Can be "", "folded", "unfolded"
fold: unfolded

Additionally, you can fold an individual code block in the Markdown file using the following syntax:

1
2
3
{% codeblock "optional file name" lang:code_language_name >folded %}
...code block content...
{% endcodeblock %}

Cover & Thumbnail

You can add a cover image to your post by adding the cover property in post’s front-matter:

post.md
1
2
3
4
title: Getting Started with Icarus
cover: /gallery/covers/cover.jpg
---
Post content...

Similarly, you may set the thumbnail of your post in the front-matter as well:

post.md
1
2
3
4
title: Getting Started with Icarus
thumbnail: /gallery/thumbnails/thumbnail.jpg
---
Post content...

The thumbnail will show in the archive page as well as in the recent post widget.

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. 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.

Read Time

You can show a word counter and the estimated reading time of your article above the article title by setting readtime to true in the article section.

_config.icarus.yml
1
2
article:
readtime: true

Article Licensing

You can show a section at the end of your posts/pages describing the licensing of your work. Both text and icons are accepted as license links. This configuration is the same as links in the navigation bar or the footer:

_config.icarus.yml
1
2
3
4
5
6
7
article:
# Article licensing block
licenses:
Creative Commons:
icon: fab fa-creative-commons
url: 'https://creativecommons.org/'
'CC BY-NC-SA 4.0': 'https://creativecommons.org/licenses/by-nc-sa/4.0/'

To make a sidebar fixed when you scroll the page, set the sticky setting of that sidebar to true in the sidebar section.

_config.icarus.yml
1
2
3
4
5
sidebar:
left:
sticky: false
right:
sticky: true

Other Configurations

You can refer to the Icarus User Guide to learn more about third-party plugins, widgets, and CDN provider configurations.

Configuration Files and Priority

Apart from the default theme configuration file _config.icarus.yml, Icarus also looks at the following locations for alternative configurations:

  • The site configuration file at _config.yml
  • Layout configuration files at _config.post.yml and _config.page.yml
  • Post/page’s front-matter
  • (Deprecated) Legacy theme configuration file at themes/icarus/_config.yml
  • (Deprecated) Legacy layout configuration file at themes/icarus/_config.post.yml and themes/icarus/_config.page.yml

Layout Configuration Files

Layout configuration files follow the same format and definitions as theme configuration files. The configurations in _config.post.yml apply to all posts, and those in _config.page.yml apply to all custom pages. They both override configurations in theme configuration files.

For example, you can adopt a two-column layout for all posts in _config.post.yml:

_config.post.yml
1
2
3
4
5
6
7
8
9
10
widgets:
-
type: recent_posts
position: left
-
type: categories
position: left
-
type: tags
position: left

while keeping a three-column layout in all other pages:

_config.icarus.yml
1
2
3
4
5
6
7
8
9
10
widgets:
-
type: recent_posts
position: left
-
type: categories
position: right
-
type: tags
position: right

Post/Page Front-matter

If you wish to override theme configurations only for a certain post/page, you can set them in the front-matter of that post/page. For example, you can change the code block highlight theme of a single post by setting it in that post’s front-matter like the following:

source/_post/some-post.md
1
2
3
4
5
6
7
title: My first post
date: '2015-01-01 00:00:01'
article:
highlight:
theme: atom-one-dark
---
# Some Post

The above setting will always override the article.highlight in _config.post.yml and _config.icarus.yml for that post. This layered configuration scheme is handy for differentiating page customizations and optimizations for different audiences. For instance, you can enable faster CDNs or a localized comment service based on the country and language of your page viewers.

However, it should be noted that post or page attributes defined by Hexo will not override the theme configurations from the front-matter. Examples are title, date, updated, comments, layout, source, photos, and excerpt.

Site Configuration File

All configuration sources listed above, including theme configuration files, layout configuration files, and post/page front-matter, will override the site configuration file only for configurations used by Icarus. For instance, title in the _config.icarus.yml will override title in the _config.yml, but new_post_name will not since it is not used by Icarus.

Also, the theme_config option in the site configuration file will merge with and override theme configurations from theme configuration files. However, using this option is highly discouraged.

Conclusion

In conclusion, the scopes of the configuration sources and their priorities are:

  • For a certain post or page

    • Post/Page front-matter overrides all following sources.
    • Layout configuration files override all following sources.
    • theme_config option in the site configuration file overrides all following sources.
    • Theme configuration files override all following sources.
    • The site configuration file.
  • For all posts or pages

    • Layout configuration files override all following sources.
    • theme_config option in the site configuration file overrides all following sources.
    • Theme configuration files override all following sources.
    • The site configuration file.
  • For all posts, pages, and index pages

    • theme_config option in the site configuration file overrides all following sources.
    • Theme configuration files override all following sources.
    • The site configuration file.

Configuration Generation and Validation

All Icarus theme configurations are written in YAML language. Icarus will automatically generate the default configuration file _config.icarus.yml from a set of JSON schemas if it does not exist. That’s why you don’t see an example configuration file (such as _config.yml.example) under the theme directory. Most of the JSON schemas are in the <icarus_directory>/include/schema directory, while the others are in the ppoffice/hexo-component-inferno repository. You can attach the --icarus-dont-generate-config flag to your hexo commands to prevent automatic configuration generation.

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 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 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 not recommended to do so.

hexo log
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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'
}
]

Additionally, Icarus will execute migration scripts to upgrade the default theme configuration file to the newest version if it is not. These scripts are in the <icarus_directory>/include/migration directory. You may disable the upgrade by appending the --icarus-dont-upgrade-config flag to your hexo commands. Finally, Icarus will also check the Node.js package dependencies and remind you to install them if you haven’t.

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

Vector Landscape Vectors by Vecteezy

Author

PPOffice

Posted on

2020-03-01

Licensed under

CC BY-NC-SA 4.0

Your browser is out-of-date!

Update your browser to view this website correctly.&npsb;Update my browser now

×