Bryan Lee
Bryan Lee

Musings about growth, software engineering, and tech.

Blogging

How to successfully integrate Netlify CMS with Hexo

If you’re using Hexo static site generator and trying to integrate Netlify CMS in using the official instructions, you may get a cryptic error message when you try to access the Netlify CMS admin page: Error: Failed to load config.yml (404).

You’ve gone through the instructions twice and verified that config.yml is correctly inside your admin folder. Why are you still getting this error message?

It turns out that Hexo automatically converts YML files inside the source folder to a JSON file when it builds. Although you have correctly placed your config.yml file, it is no longer available in the built version. Not to worry, you’ll just need to tell Netlify to manually insert the config.yml when it builds.

In your Netlify settings > Continuos Deployment, change your build command from hexo generate to hexo generate; cp source/admin/config.yml public/admin/config.yml. Now your config.yml gets copied correctly into the admin folder by Netlify when you deploy.

The slight inconvenience is that you can’t access Netlify CMS locally if you are running your development server with hexo server.

Layout Issues

Now you’ve fixed this and logged in to your Netlify CMS, but something still does not look fully correct with your page. The Netlify CMS pages have your entire theme layout rendered inside as well.

Again, this is due to how Hexo generates static pages. It turns out that even non markdown files (remember your admin/index.html file?) get processed like normal markdown files. The admin page markup thus gets rendered inside your theme layout.

Understanding this, we can make use of this same mechanism and disable the layout rendering by Hexo. Add this front matter to the top of your admin/index.html file:

---
layout: false
---

Deploy by pushing all your changes to Github and you should now have a perfectly working Netlify CMS integrated.

    comments powered by Disqus