DEV Community

Cover image for Hexo - local configuration
Russ Hammett
Russ Hammett

Posted on • Originally published at on


Hexo - local configuration

Exploring how to use merged config files for setting up a “local” vs “prod” workflow in Hexo.

Dave (from and I were talking a bit about thumbnails, feature images, and our local vs deployed dev process in the coding blocks slack channel today. I discovered that a bit of research was needed on how to avoid changing config files when switching between a local dev and deployed situation.

The answer lies in numerous config files that can get merged together for local development…

My url from _config.yml was pointing to my actual domain of This caused issues when writing a new post because of images I had intended to use like “hexo-logo.png” would have its full URL built out as [url]/[myPost]/hexo-logo.png, which in my case would be The “URL” portion of my config file was being injected in, but since these images did not exist out on the internet yet, I was unable to confirm the image actually “worked”.

This led me to update my url to “localhost:4000”. Now my images were showing up (when I spelled the image name right) but I now had to deal with another problem. I needed to remember to change my url back to my actual domain of “”.

Multiple config files to the rescue!

Poking around the hexo documentation I happened across: Using an Alternate Config. Going this route, I would be able to utilize multiple configuration files that get “merged” together, with the values further down the “chain” of configuration files taking priority.

With this in mind, I created a new config file:


url: http://localhost:4000
Enter fullscreen mode Exit fullscreen mode

That’s it… Now, we just need to use this file when generating and server-ing… as so:

hexo clean && hexo generate --config _config.yml,_config.local.yml && hexo server --config _config.yml,_config.local.yml
Enter fullscreen mode Exit fullscreen mode

In the above (which I put in a .bat file called “serveLocal.bat”) we’re saying use the “_config.yml”, THEN the “_config.local.yml” file when building and serving. This causes the “_config.yml”s url property to be overwritten - going from “" to “http://localhost:4000".

Now, when developing locally, rather than running hexo generate && hexo server, I simply run the “serveLocal.bat” file. When pushing to GitHub, which then kicks off a built to Netlify, the normal and original “_config.yml” file is the only file that gets considered under that build’s build step of hexo generate.

One additional setting that almost immediately came to mind for the “config.local.yml” file was render_drafts: true. With this option in _only the local config file, I can ensure that I’m able to view my drafts locally, while keeping them out of my deployed blog in instances where I want to check some drafts into my git repo - without having to remember to change configuration settings!

Wrap up

Today I explored working with multiple configuration files in my hexo development process. The full “_config.local.yml” that I’m using is:

url: http://localhost:4000
render_drafts: true
Enter fullscreen mode Exit fullscreen mode

I’m using a bat file for local generation and serving:

hexo clean && hexo generate --config _config.yml,_config.local.yml && hexo server --config _config.yml,_config.local.yml
Enter fullscreen mode Exit fullscreen mode

And note that a “_multiconfig.yml” file is automatically generated based on the merge of your configuration files for (I assume) easier debugging.

Hexo logo by:


Top comments (0)

Timeless DEV post...

Git Concepts I Wish I Knew Years Ago

The most used technology by developers is not Javascript.

It's not Python or HTML.

It hardly even gets mentioned in interviews or listed as a pre-requisite for jobs.

I'm talking about Git and version control of course.

One does not simply learn git