From 371f6f824c465235ca280b8b85e193e5429be959 Mon Sep 17 00:00:00 2001 From: ppoffice Date: Fri, 1 May 2020 01:01:59 -0400 Subject: [PATCH] chore(doc): update en theme configuration post --- source/_posts/en/Configuring-Theme.md | 484 +++++++++++++------------- source/_posts/en/Getting-Started.md | 4 +- 2 files changed, 242 insertions(+), 246 deletions(-) diff --git a/source/_posts/en/Configuring-Theme.md b/source/_posts/en/Configuring-Theme.md index 669445f..903e52d 100644 --- a/source/_posts/en/Configuring-Theme.md +++ b/source/_posts/en/Configuring-Theme.md @@ -10,213 +10,53 @@ language: en 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 cover the mechanisms used by Icarus to configure your site and going through the format -and meaning of some configuration settings. +Icarus' default theme configuration file is `themes/icarus/_config.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. -
-This article is also available in: 简体中文. + -## Generate and Validate the Configuration - -An Icarus theme configuration file is written in [the `YAML` language](https://yaml.org/), and the default configuration file -`themes/icarus/_config.yml` is generated automatically from a set of [JSON schemas](https://json-schema.org/) when the theme is processed by Hexo and you don't have -a theme configuration file available at that time. -That's why you don't see an example file (`_config.yml.example`) under your theme directory and there's no -need to create `_config.yml` yourself. -Most of the JSON schema definitions sit in the `themes/icarus/include/schema` directory and the others are -in the [ppoffice/hexo-component-inferno](https://github.com/ppoffice/hexo-component-inferno) repository. -You may attach the `--icarus-dont-generate-config` flag to your `hexo` commands to prevent configuration -generation. - -The theme will also validate your configurations using these schemas every time you execute a `hexo` command -in your site directory. -If anything goes wrong during the validation, Icarus will print out the exact location of the misconfiguration -and it's error type. For example, the following messages tell us that the value of `logo` setting should be -either a string or an object, instead of an integer. -You could ignore the warnings or append the `--icarus-dont-check-config` flag to your `hexo` commands to skip -the validation, but it is not recommended to do so. - -{% codeblock "hexo log" %} -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 %} - -Additionally, Icarus will try to use the migration scripts to upgrade your configuration to the newest version. -These scripts are in the `themes/icarus/include/migration` directory. -You may disable the upgrade by append 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. - -## Additional Configuration Files and Priority - -Apart from the default theme configuration file at `themes/icarus/_config.yml`, Icarus also look at configurations -from the following sources: - -- `themes/icarus/_config.post.yml` and `themes/icarus/_config.page.yml` -- Post/page's [front-matter](https://hexo.io/docs/front-matter.html) -- Site `_config.yml` in the root directory - -`_config.post.yml` and `_config.page.yml` follows the same format and definitions of the default theme configuration -file. -You may put post-specific configurations in `_config.post.yml`, and these configurations will override the default -theme configurations. -For example, you can apply a two-column layout for all posts by moving all widgets to the left side of the page while keeping a three-column layout in other pages: - -{% 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 %} - -Similarly, `_config.page.yml` overrides the default theme configurations and only applies to all Hexo pages. -Additionally, if you wish to override theme configurations for a certain post/page, you can put them in the -front-matter of that post/page. -For example, if you can change the highlight.js theme of the code blocks by adding the setting in the post's -front-matter like this: - -{% codeblock source/_post/some-post.md lang:yaml %} -title: My first post -date: '2015-01-01 00:00:01' -article: - highlight: - theme: atom-one-dark ---- -# Some Post -{% endcodeblock %} - -The above setting in the front-matter will always override the same setting in the `_config.post.yml` and -`_config.yml`. -This feature can be very useful for displaying customized/optimized pages to a specific audience. -For example, you can enable faster CDNs or a localized comment service based on the country and language of the -page viewers. -However, it should be noted that the post or page attributes defined by Hexo in the front-matter will not -override the theme configuration files. Examples are: - -- `title` -- `date` -- `updated` -- `comments` (not `comment`) -- `layout` -- `source` -- `photos` -- `excerpt` - -Finally, the site configuration file `_config.yml` in the root directory will be override by all other -configuration files for the settings used by the theme. -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. - -In conclusion, the scopes of the configuration files and their priorities are - - - - - - - - - - - - - - - - - - - - - -
A certain post/page
-
    -
  • front-matter overrides
    • -
  • themes/icarus/_config.post.yml or themes/icarus/_config.page.yml overrides
    • -
  • themes/icarus/_config.yml overrides
    • -
  • _config.yml
    • -
-
All posts/pages
-
    -
  • themes/icarus/_config.post.yml or themes/icarus/_config.page.yml overrides
    • -
  • themes/icarus/_config.yml overrides
    • -
  • _config.yml
    • -
-
All HTML pages
-
    -
  • themes/icarus/_config.yml overrides
    • -
  • _config.yml
    • -
-
- - -## Theme Configuration Walkthrough +## 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. + {% codeblock themes/icarus/_config.yml lang:yaml %} version: 3.0.0 {% endcodeblock %} -This version code is related to and but not always the same as the theme version code. -It is used when Icarus upgrade the configuration file via migration scripts. -You should not change it by yourself. - ### Theme variant +Choose a skin for Icarus. +`"default"` and `"cyberpunk"` are supported values currently. +You can take a look at the Cyberpunk variant {% post_link demo/Cyberpunk "here" %}. + {% codeblock themes/icarus/_config.yml lang:yaml %} variant: default {% endcodeblock %} -Choose a skin for Icarus. -"default" and "cyberpunk" are supported currently. -You can take a look at the Cyberpunk variant {% post_link demo/Cyberpunk "here" %}. - ### Logo +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: + {% codeblock themes/icarus/_config.yml lang:yaml %} logo: /img/logo.svg {% endcodeblock %} -Set the logo of your site which will display on the navigation bar and the footer. -The value of the `logo` setting can either be a path/URL to your logo image, or it can be the following if -you want text instead of an image as the logo +Or if you want the text instead, you can set it like the following: {% codeblock themes/icarus/_config.yml lang:yaml %} logo: @@ -225,15 +65,20 @@ logo: ### Favicon +You can specify the path or URL to your site's favicon in the `head` section. + {% codeblock themes/icarus/_config.yml lang:yaml %} head: favicon: /img/favicon.svg {% endcodeblock %} -You may specify the path or URL to your site's favicon in the `head` section. - ### 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](https://hexo.io/docs/helpers.html#open-graph) for details on each setting. + {% codeblock themes/icarus/_config.yml lang:yaml >folded %} head: open_graph: @@ -272,13 +117,14 @@ head: fb_app_id: {% endcodeblock %} -You may set the Open Graph settings in the `head` section. -You should leave some of the settings blank in the theme configuration file and only set those settings -in the front-matter of your post when needed. -Please refer to [Hexo documentation](https://hexo.io/docs/helpers.html#open-graph) for details of each setting. - ### 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](https://developers.google.com/search/docs/guides/intro-structured-data) +for details on each setting. + {% codeblock themes/icarus/_config.yml lang:yaml >folded %} head: structured_data: @@ -299,14 +145,14 @@ head: image: {% endcodeblock %} -You may set the Google Structured Data settings in the `head` section. -You should leave most of the settings blank in the theme configuration file and only set those settings -in the front-matter of your post when needed. -Please refer to [Search for Developers](https://developers.google.com/search/docs/guides/intro-structured-data) for details of -each setting. - ### Page Metadata +You can add custom `` 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 the `meta` setting should be in the `=` format +with `field_name` and `field_value` represent the field and value of the `` tag respectively. +Separate the `=` pairs with `;` if the `` tag has multiple fields and values. + {% codeblock themes/icarus/_config.yml lang:yaml %} head: meta: @@ -314,21 +160,21 @@ head: - 'name=generator;content="Hexo 4.2.0"' {% endcodeblock %} -You can add custom HTML `` tags to all pages in the `meta` setting of the `head` section. -Each meta tag should appear as an item of the `meta` array. -The fields of the tag should be in the `=` format and they are separated by `;`. - ### RSS +You can add a link to your RSS feed at the `rss` setting in the `head` section. + {% codeblock themes/icarus/_config.yml lang:yaml %} head: rss: /path/to/atom.xml {% endcodeblock %} -You can add an RSS link in the page head via this setting. - ### Navigation Bar +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 `: ` to the `menu` setting. +To put links on the right side of the navigation bar, add `: ` to the `links` setting. + {% codeblock themes/icarus/_config.yml lang:yaml %} navbar: # Naviagtion menu items @@ -346,10 +192,7 @@ navbar: url: 'https://github.com/ppoffice/hexo-theme-icarus' {% endcodeblock %} -The `navbar` section defines the links showing in the navigation bar. -You may add arbitrary links to the navigation menu by adding `: ` to the `menu` setting. -If you wish to add links on the right side of the navigation bar, please add `: ` to the `links` setting. -You can even use a FontAwesome icon instead of pure text as link with the following format: +You can display a FontAwesome icon instead of text-only link with the following format: {% codeblock "Link format" lang:yaml %} : @@ -359,6 +202,9 @@ You can even use a FontAwesome icon instead of pure text as link with the follow ### Footer +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. + {% codeblock themes/icarus/_config.yml lang:yaml %} footer: links: @@ -373,11 +219,18 @@ footer: url: 'https://github.com/ppoffice/hexo-theme-icarus' {% endcodeblock %} -You may add arbitrary links to the page footer in the `links` setting of the `footer` section. -The format of the links is the same as `links` in the `navbar` section. - ### 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](https://github.com/highlightjs/highlight.js/tree/9.18.1/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. + {% codeblock themes/icarus/_config.yml lang:yaml %} article: highlight: @@ -390,15 +243,7 @@ article: fold: unfolded {% endcodeblock %} -If you have already enabled code highlighting in Hexo, you may customize the code blocks with `highlight` settings in the `article` -section. -You can choose a theme from all themes listed in [highlight.js/src/styles](https://github.com/highlightjs/highlight.js/tree/9.18.1/src/styles) -and put the file name without the `.css` extension in the `theme` setting. -You may also turn the "copy" button on or off by setting `clipboard` to `true` or `false`. -Finally, if you wish to fold or unfold all code blocks, please set the `fold` setting to `folded` or `unfolded`. -The folding feature can also be disabled if you leave the `fold` setting empty. -Moreover, you can fold individual code blocks in the markdown file using the following syntax: - +Additionally, you can fold an individual code block in the Markdown file using the following syntax: ``` {% codeblock "optional file name" lang:code_language_name >folded %} @@ -408,40 +253,44 @@ Moreover, you can fold individual code blocks in the markdown file using the fol ### Thumbnail -You can add thumbnail images to your posts in two steps. -First, make sure the thumbnail is enabled in the theme's configuration file: +You can add a thumbnail image to your post in two steps: -{% codeblock themes/icarus/_config.yml lang:yaml %} -article: - thumbnail: true -{% endcodeblock %} +1. Make sure the thumbnail is enabled in the theme configurations: -Then, provide an URL or path to the image file in the front-matter of your post: + {% codeblock themes/icarus/_config.yml lang:yaml %} + article: + thumbnail: true + {% endcodeblock %} -{% codeblock post.md lang:yaml %} -title: Getting Started with Icarus -thumbnail: /gallery/thumbnails/desert.jpg ---- -Post content... -{% endcodeblock %} +2. Provide a path or URL to the thumbnail image file in the front-matter of your post: -The image path you put in the front-matter needs to be the absolute path or URL to the image, -or relative path to the source directory of your website. -For example, if you want to use the `/source/gallery/image.jpg` as a thumbnail, you will need to put -`/gallery/image.jpg` in the front-matter. + {% codeblock post.md lang:yaml %} + title: Getting Started with Icarus + thumbnail: /gallery/thumbnails/desert.jpg + --- + Post content... + {% endcodeblock %} + + 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 `/source/gallery/image.jpg` as a thumbnail path, 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. + {% codeblock themes/icarus/_config.yml lang:yaml %} article: readtime: true {% endcodeblock %} -You can show the word counter and estimated time on top of your article by setting `readtime` to `true` -in the `article` section. - ### Sidebar +To make a sidebar fixed when you scroll the page, set the `sticky` setting of that sidebar to `true` in +the `sidebar` section. + {% codeblock themes/icarus/_config.yml lang:yaml %} sidebar: left: @@ -450,19 +299,166 @@ sidebar: sticky: true {% endcodeblock %} -Sometimes you may want your sidebar's position to stay fixed when your page scrolls. -This can be done via the `sticky` settings in the `sidebar` section. + +### Other configurations + +You can refer to the [Icarus User Guide](/hexo-theme-icarus/tags/Icarus-User-Guide/) to learn more about +third-party plugins, widgets, and CDN provider configurations. -## Other Configuration Settings +## Configuration Files and Priority -Please refer to the [Icarus User Guide](/hexo-theme-icarus/tags/Icarus-User-Guide/) series if you are interested -in configurating third-party plugins, widgets, and CDN providers of Icarus. +Apart from the default theme configuration file at `themes/icarus/_config.yml`, Icarus also looks at the following +locations for alternative configurations: + +- `themes/icarus/_config.post.yml` and `themes/icarus/_config.page.yml` +- Post/page's [front-matter](https://hexo.io/docs/front-matter.html) +- Site `_config.yml` in the root directory + +`_config.post.yml` and `_config.page.yml` follow the same format and configuration definitions as the default theme +configuration file. +You can put configurations that apply to all posts in `_config.post.yml`, and these configurations will override +`themes/icarus/_config.yml`. +For example, you can adopt a two-column layout in all posts by moving all widgets to one side of the page while +keeping a three-column layout in other pages: + +{% 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 %} + +Similarly, `_config.page.yml` applies to all Hexo pages and overrides the default theme configurations. + +If you wish to override configurations only for a certain post/page, you can put these configurations 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: + +{% codeblock source/_post/some-post.md lang:yaml %} +title: My first post +date: '2015-01-01 00:00:01' +article: + highlight: + theme: atom-one-dark +--- +# Some Post +{% endcodeblock %} + +The above setting will always override the `article.highlight` in `_config.post.yml` and `_config.yml` +for that post. +This layered configuration system is handy for differentiating page customizations and optimizations +for different audiences. +For example, 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 inherit post or page attributes defined by Hexo will not override the +theme configurations from the front-matter. +Examples are: + +- `title` +- `date` +- `updated` +- `comments` (not `comment`) +- `layout` +- `source` +- `photos` +- `excerpt` + +Lastly, any other configuration files listed above will override the site configuration file `_config.yml` +for the settings used by the Icarus. +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. + +In conclusion, the scopes of the configuration locations and their priorities are: + +- A certain post or page + + - front-matter overrides all configurations below. + - `themes/icarus/_config.post.yml` and `themes/icarus/_config.page.yml` override all configurations below. + - `themes/icarus/_config.yml` overrides all configurations below. + - `_config.yml` + +- All posts or pages + + - `themes/icarus/_config.post.yml` or `themes/icarus/_config.page.yml` override all configurations below. + - `themes/icarus/_config.yml` overrides all configurations below. + - `_config.yml` + +- All posts, pages, and index pages + + - `themes/icarus/_config.yml` overrides all configurations below. + - `_config.yml` -
+## Configuration Generation and Validation + +All Icarus theme configurations are written in the [YAML language](https://yaml.org/). +The default configuration file `themes/icarus/_config.yml` is generated automatically from a set of +[JSON schemas](https://json-schema.org/) when Hexo processes the theme. +That's why you don't see an example file (`_config.yml.example`) under the theme directory. +Most of the JSON schemas are in the `themes/icarus/include/schema` directory, while the others are +in the [ppoffice/hexo-component-inferno](https://github.com/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 it's 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. + +{% codeblock "hexo log" %} +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 %} + +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 `themes/icarus/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 diff --git a/source/_posts/en/Getting-Started.md b/source/_posts/en/Getting-Started.md index e00a40f..cc0fe77 100644 --- a/source/_posts/en/Getting-Started.md +++ b/source/_posts/en/Getting-Started.md @@ -9,10 +9,10 @@ language: en Welcome to the Icarus documentation site! Icarus is a simple, delicate, and modern theme for the static site generator Hexo. It strives to be elegant in design while simple and straightforward to use. -Its versatile and flexible configuration system to let power users lay out their sites to the finest details. +Its versatile and flexible configuration system enables power users lay out their sites to the finest details. Icarus also offers a wide range of plugins and widgets to meet your various customization and optimization needs. -Moreover, its refreshed internal implementation enables better IDE support and third-party integration, which +Moreover, its refreshed implementation enables better IDE support and third-party integration, which open to a sea of improvement possibilities.