hexo_blog_issues

Hexo Blog Setup Issues Summary

Issue 1: Web Page Fails to Render After Deployment

Description

After deploying the Hexo blog to a hosting platform such as GitHub Pages, the web page may not render properly. This is often due to misconfigurations in the Hexo _config.yml file.

Symptoms

• The blog deploys without errors, but when visiting the site, it shows a blank page or a layout without any styles.
• Console logs in the browser may show missing files or 404 errors.

Solution

Verify and Adjust the _config.yml Settings:

1. Correct root Setting:

   • Ensure that the root setting in your _config.yml matches the directory structure of your deployment environment. For example, if your blog is accessible at https://username.github.io/blog, set root: /blog/.
   • If your blog is hosted at the root of a domain, e.g., https://username.github.io, make sure root is set to /.

2. Check URL Configuration:

   • The url setting should match your domain

Successful Configuration Example

Here’s an example of a correctly configured _config.yml that resolves the issue:

url: https://yuuee-www.github.io/blog/
root: /

Issue 2: Images Not Displayed in Posts After Changing Themes and Redeploying

Description

After switching themes in a Hexo blog and redeploying, images located in the source directory may not appear in the generated public directory. This results in images not being displayed in blog posts when viewed on the web.

Symptoms

• Blog posts are missing images that are supposed to be embedded.
• No errors during deployment, but the images from the source directory do not appear in the public directory, resulting in broken image links on the live site.

Resolution

Configure the _config.yml File

The issue often stems from the post_asset_folder setting in Hexo’s _config.yml file not being enabled. By default, this setting is false, which means images stored in post asset folders aren’t copied to the public directory during the generation process.

Steps to Resolve:

1. Open your Hexo blog’s _config.yml file.
2. Locate the post_asset_folder setting.
3. Change the value of post_asset_folder from false to true:

   post_asset_folder: true
   

Additional Notes

Use these commands for routine Hexo blog maintenance:

• hexo clean
• hexo g
• hexo d

Recommended Reading

For advanced tips, check out this guide: Optimizing and Troubleshooting Hexo .