Hexo & GitHub Actions - “No artifacts named ‘github-pages’” Error

After migrating to Hexo, I tried setting up GitHub Pages deployment via GitHub Actions, following the official guide GitHub Pages. Unfortunately, my workflow consistently failed with the error:

No artifacts named "github-pages" were found for this workflow run.

Solution:

My guess is there could be a potential incompatibility or version mismatch between the actions/upload-pages-artifact v3 and actions/deploy-pages v4.

To address this, just to explicitly ensure the Pages configuration was up-to-date before the deployment step.

1
2

- name: Configure GitHub Pages
  uses: actions/configure-pages@v4

My Complete GitHub Actions Workflow:

Here’s the GitHub Actions workflow file (.github/workflows/your-workflow-name.yml) that now works:

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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

name: GH Pages Deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pages: write
      id-token: write
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
      - name: Use Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Cache NPM dependencies
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-
      - name: Install Dependencies
        run: npm install    
      - name: Build
        run: npm run build
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public  
  deploy:
    needs: build
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
    - name: Configure Pages
      uses: actions/configure-pages@v4
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

Hopefully, this helps anyone else struggling with the same GitHub Actions deployment error for their static sites!

In a previous post, I shared my migration from Jekyll to Hexo for my GitHub Pages blog. In this post, I’ll go over some of the common commands I use to create posts and test my blog locally.

✍️ Create a New Post or Draft

The commands in Hexo are quite human-readable. To create a new blog post or draft, use:

1
2

$ hexo new post "My Post"
$ hexo new draft "My Draft"

This will create a Markdown file in the source/_posts folder for posts, or in the source/_drafts folder for drafts. The keywords "post" and "draft" refer to the layout used for the file. You can customize these layouts in the scaffolds folder.

You can also create your own custom layout file inside the scaffolds folder and use it when creating a new post. For example:

1

$ hexo new mylayout "My Layout"

To move a draft to the posts folder, use the publish command instead of new. This will move the file from source/_drafts to source/_posts :

1

$ hexo publish post "My Draft"

🖥️ Run the Blog Locally

To run your blog locally, you first need to generate the static files:

1

$ hexo generate

Or use the shorthand:

1

$ hexo g

Then, start the local development server:

1

$ hexo server

By default, this will start a server at http://localhost:4000. Open that link in your browser and you’ll see your website.

Although Hexo is supposed to watch for local changes and update automatically, there are cases where a simple browser refresh doesn’t reflect your changes — especially when you modify configuration files like _config.yml. In those cases, it’s best to regenerate the static files and restart the server.

Also, we can use the clean command to remove previously generated files, to keep local repository clean.

1

$ hexo clean

✅ Summary

Here’s a quick cheat sheet:

Been using Jekyll for GitHub Pages since the beginning, but after switching out my old laptop, I never managed to get the local environment set up properly. Then the theme I was using became unmaintained—and not being able to tweak the layout locally when everything started breaking was seriously frustrating.

Recently came across Hexo—found it pretty similar to use and super easy to host locally. What really impressed me was that it only took about 2 hours to migrate my old project to Hexo, and honestly, half of that time was just me browsing for a theme I liked.

The migration

Step 1: Create a new Hexo project

As stated on the official Hexo website, you only need Git, Node.js, and npm installed locally. Once that’s set up, just follow the instructions:

1
2
3

$ hexo init <folder>
$ cd <folder>
$ npm install

After running these commands, you should see a few files and folders created in the project directory.

Step 2: Configuration

Just like in Jekyll, configurations in Hexo are defined in the _config.yml file. You can modify the settings there as needed.

There are two key configurations to pay attention to:

1. new_post_name:
   By default, Hexo generates new post filenames based on the input title, like title.md. To match Jekyll’s convention more closely, you can update it to include the date:

   1	new_post_name: ':year-:month-:day-:title.md'

2. Asset folder management:
   Unlike Jekyll, Hexo offers built-in asset folder handling. There are two ways to manage assets:

   • Global asset folder (similar to Jekyll):
     You can manually organize files however you like. In this case, no changes to _config.yml are needed.

   • Post-specific asset folders:
     A more structured approach, where each post has its own associated asset folder. To enable this, update your config as follows:

     1 2 3 4

     post_asset_folder: true marked: prependRoot: true postAsset: true

     If you’ve updated new_post_name as shown above, make sure to also update the permalink setting to ensure asset paths are correctly resolved:

     1	permalink: ':year/:month/:day/:title/'

Step 3: Move data

With the configurations set, we’re good to go. The nice thing is that Hexo’s file structure is quite similar to Jekyll’s—you just need to move everything inside your old _posts folder into the source/_posts folder in your Hexo project.

For asset folder, as mentioned earlier, if you prefer to organize files manually, simply copy the asset folders into the source directory. Everything under the source folder will be copied to the public folder when generating static pages. This means you can reference images directly using syntax like ![](/images/image.jpg). It won’t show the image immediately in the markdown editor, but it will point to the correct location once the project is built.

If you’re using post_asset_folder = true to manage asset folders, there’s a bit more setup. Run the following command to create asset folders for your existing posts and then move the corresponding files into them:

1

mkdir $(basename -a -s .md ./*.md)

Also, make sure to simplify your image paths—you only need something like ![](image.jpg) inside the post.

Step 4: Choose a theme

One last thing, choose a theme for the website. There are way more themes than I expected, so I ended up picking one at random: Icarus. Also, switching between themes is super easy—just follow the instructions, and it shouldn’t take more than five minutes.

Step 5: Deploy

The website offers two deployment options. The more common approach is to use One-Command Deployment. In this case, you don’t need to update your repository manually—the deployer will upload all the static files (HTML, CSS, etc.) to GitHub once the build is complete.
Note: If you choose this method, the repository will only contain the generated static files after deployment.

The other way to deploy is to commit all your local files (make sure public/ is added to your .gitignore), then use a GitHub Action to build and deploy the website.

Voila! The migration is officially done.