Written by: Geoffrey Callaghan

how to create a Hexo theme

How To Create A Hexo Theme

Creating a Hexo theme involves customizing the layout, styles, and functionality of your Hexo blog. Hexo is a static site generator built with Node.js, and themes are typically organized with EJS templates and CSS. Here’s a step-by-step guide to help you create a Hexo theme:

Step 1: Set Up Your Environment

  1. Install Node.js and npm: Ensure you have Node.js and npm installed. You can download and install from nodejs.org.

  2. Install Hexo CLI: Install the Hexo Command Line Interface globally.

    npm install -g hexo-cli
  3. Create a New Hexo Project: Initialize a new Hexo project.

    hexo init my-hexo-blog
    cd my-hexo-blog
    npm install

Step 2: Understand Hexo Directory Structure

Hexo uses a specific directory structure:

  • source: Contains the content (Markdown files).
  • themes: Directory where themes are stored.
  • public: Output directory where Hexo generates the static site.

Step 3: Create Your Hexo Theme

  1. Create a New Theme Directory: Inside the themes directory of your Hexo project, create a new directory for your theme.

    cd themes
    mkdir my-custom-theme
    cd my-custom-theme
  2. Initialize a package.json for Your Theme: Initialize your theme as an npm package.

    npm init -y
  3. Create Theme Files:

    • Layouts: Hexo uses EJS templates for layouts. You can create various layouts such as index.ejs, post.ejs, page.ejs, etc.
    • CSS: Create a style.css or similar for your theme’s styles.
    • Partial Templates: You can create partials for components like header, footer, sidebar, etc.

    Here’s a basic example of a layout (index.ejs):

    <!DOCTYPE html>
      <meta charset="utf-8">
      <title><%= config.title %></title>
      <link rel="stylesheet" href="<%- url_for('/css/style.css') %>">
        <h1><%= config.title %></h1>
        <p><%= config.subtitle %></p>
            <li><a href="<%= url_for('/') %>">Home</a></li>
            <li><a href="<%= url_for('/about') %>">About</a></li>
            <!-- Add more menu items as needed -->
        <% page.posts.forEach(post => { %>
            <h2><a href="<%= post.permalink %>"><%= post.title %></a></h2>
            <p><%= post.date.format('YYYY-MM-DD') %></p>
            <p><%= post.excerpt %></p>
        <% }); %>
        <p>&copy; <%= new Date().getFullYear() %> Your Blog Name</p>

    And a basic style.css for your theme’s styles:

    /* themes/my-custom-theme/source/css/style.css */
    body {
      font-family: Arial, sans-serif;
      line-height: 1.6;
      background-color: #f0f0f0;
    header {
      background-color: #007bff;
      color: white;
      padding: 10px;
    nav ul {
      list-style-type: none;
      padding: 0;
    nav ul li {
      display: inline;
      margin-right: 10px;
    nav ul li a {
      color: white;
      text-decoration: none;
    main {
      padding: 20px;
    article {
      margin-bottom: 20px;
      padding: 10px;
      background-color: white;
      border: 1px solid #ddd;
    footer {
      background-color: #007bff;
      color: white;
      text-align: center;
      padding: 10px;
      position: fixed;
      bottom: 0;
      width: 100%;

Step 4: Configure Your Theme

  1. Update _config.yml: Modify the Hexo configuration file to set your theme.

    # File: _config.yml
    theme: my-custom-theme
  2. Customize Theme Configuration: You can add custom configuration options in your theme’s package.json or directly in your theme files (_config.yml or JavaScript).

Step 5: Use and Customize Your Theme

  1. Add Content and Test: Add content (Markdown files) to your Hexo site and test your theme by running Hexo locally.

    hexo server

    This command will start a local server where you can preview your Hexo blog with the custom theme.

Step 6: Publish and Share Your Theme

  1. Publish Your Theme (Optional): If you want to share your theme with others, you can publish it as an npm package or make it available in a public repository.

    npm publish --access public

Final Steps

  1. Test and Document Your Theme: Test your theme thoroughly across different content types and scenarios. Provide clear documentation (README.md) on how to install, use, and customize your Hexo theme.

By following these steps, you can create a custom Hexo theme tailored to your specific design and functional requirements, making your blog unique and personalized.