[Hexo Best Practices] Use alternate site or theme configuration to minimal invasive site and theme configuration in Hexo

Posted on In , , Views: Word count in article: 2.7k Reading time ≈ 2 mins.

Configration

Hexo is a fast, simple & powerful blog framework. It use plugins to provide features powerful APIs for limitless extensibility. Various plugins are available to support most template engines (EJS, Pug, Nunjucks, and many others). Easily integrate with existing NPM packages (Babel, PostCSS, Less/Sass, etc).

By default, there are the following configuration(YAML or JSON) files in Hexo:

  • _config.yml

  • config[theme].yml

  • themes/[theme]/_config.yml

We can directly modify the above configuration file, but this is a litter intrusive for Hexo.

Recommend to use alternate site or theme configuration to minimal invasive site and theme configuration in Hexo.

Alternate Site Configuration

Using multiple files combines all the config files and saves the merged settings to _multiconfig.yml. The later values take precedence. It works with any number of JSON and YAML files with arbitrarily deep objects. Note that no spaces are allowed in the list.

A custom config file path can be specified by adding the --config flag to your hexo commands with a path to an alternate YAML or JSON config file, or a comma-separated list (no spaces) of multiple YAML or JSON files.

Step 1. Create a new _overrideconfig.yml file to store the override configuration about the site or theme.

Step 2. Use --options.

  • Use --options in hexo command line:

    1
    2
    # use '_config.yml' & '_overrideconfig.json', prioritizing '_overrideconfig.json'
    $ hexo server --config _config.yml,_overrideconfig.json

  • Or in package.json for npm.

    1
    2
    3
    4
    5
    6
    7
    8
    # package.json

        "scripts": {
            "build": "hexo generate --config _config.yml,_overrideconfig.yml",
            "clean": "hexo clean --config _config.yml,_overrideconfig.yml",
            "deploy": "hexo deploy --config _config.yml,_overrideconfig.yml",
            "server": "hexo server --config _config.yml,_overrideconfig.yml"
        },

Alternate Theme Config

Hexo themes are independent projects, with separate _config.yml files.

Instead of forking a theme, and maintaining a custom version with your settings, you can configure it from somewhere else:

from theme_config in site’s primary configuration file

The file should be placed in your site folder, both yml and json are supported. theme inside _config.yml must be configured for Hexo to read _config.[theme].yml

1
2
3
4
5
6
7
# _config.yml

theme: "my-theme"

theme_config:
  foo:
    bar: 'a - theme_config'
1
2
3
4
5
# _config.my-theme.yml

bio: "My theme_config bio - _config.my-theme.yml"
foo:
  bar: 'a'
1
2
3
4
5
6
# themes/my-theme/_config.yml

bio: "Some generic bio"
logo: "a-cool-image.png - themes/my-theme/_config.yml"
  foo:
    baz: 'b'

Resulting in theme configuration:

1
2
3
4
5
6
7
8
{
  bio: "My awesome bio - _config.my-theme.yml",
  logo: "a-cool-image.png - themes/my-theme/_config.yml",
  foo: {
    bar: "a - theme_config",
    baz: "b"
  }
}

References

[1] Configuration | Hexo - https://hexo.io/docs/configuration.html

[2] Hexo - https://hexo.io/