Themes

It’s easy to build a Hexo theme - you just have to create a new folder. To start using your theme, modify the theme setting in your site’s _config.yml. A theme should have the following structure:

.
├── _config.yml
├── languages
├── layout
├── scripts
└── source

_config.yml

Theme configuration file. Unlike the site’s primary configuration file, modifying this doesn’t require a server restart.

languages

Language folder. See internationalization (i18n) for more info.

layout

Layout folder. This folder contains the theme’s template files, which define the appearance of your website. Hexo provides the Nunjucks template engine by default, but you can easily install additional plugins to support alternative engines such as EJS or Pug. Hexo chooses the template engine based on the file extension of the template (just like the posts). For example:

layout.ejs   - uses EJS
layout.njk   - uses Nunjucks

See templates for more info.

scripts

Script folder. Hexo will automatically load all JavaScript files in this folder during initialization. For more info, see plugins.

source

Source folder. Place your assets (e.g. CSS and JavaScript files) here. Hexo ignores hidden files and files or folders prefixed with _ (underscore).

Hexo will process and save all renderable files to the public folder. Non-renderable files will be copied to the public folder directly.

Publishing

When you have finished building your theme, you can publish it to the theme list. Before doing so, you should run the theme unit test to ensure that everything works. The steps for publishing a theme are very similar to those for updating documentation.

  1. Fork hexojs/site

  2. Clone the repository to your computer and install dependencies.

    $ git clone https://github.com/<username>/site.git
    $ cd site
    $ npm install

  3. Create a new yaml file in source/_data/themes/, use your theme name as the file name

  4. Edit source/_data/themes/<your-theme-name>.yml and add your theme. For example:

    description: A brand new default theme for Hexo.
    link: https://github.com/hexojs/hexo-theme-landscape
    preview: http://hexo.io/hexo-theme-landscape
    tags:
      - official
      - responsive
      - widget
      - two_column
      - one_column

  5. Add a screenshot (with the same name as the theme) to source/themes/screenshots. It must be a 800*500px PNG.

  6. Push the branch.

  7. Create a pull request and describe the change.