Good god I wish I could get the last 3 hours of my life back. Hopefully I will save you some time with this one.

Situation

So you’ve got your Hexo blog written and built locally, and man it looks good. You want to push the repo to Github pages to deploy it. Unfortunately, Github Pages assumes your index.html file is in the root directory. With Hexo, your directory structure might look like this:

1
2
3
4
5
6
7
8
9
.
├── _config.yml
├── package.json
├── scaffolds
├── public <---this is where my HTML gets built
├── source
| ├── _drafts
| └── _posts
└── themes

I attempted to change the _config.yml to spit out the HTML to the root directory of the repo, but that broke everything. This means that Github pages is of no help to me (and maybe you) in its current form since you can’t easily tell GHP that the html is not in the root.

Solution

Three hours and dozens of blogs/help pages later, this is the solution that ended up working

  1. Open _config.yml and set the public_dir parameter to docs (it MUST be spelled d-o-c-s).
  2. Rebuild. Something important here–if you’re using a custom domain like me, your CNAME file needs to be in the docs folder, so you to have manually create that again before you push. Don’t edit this on the Settings page of the repo. It’s easier to just do it here and push without issue.

    1
    2
    3
    $ hexo clean
    $ hexo generate
    $ echo "yourdomain" >> docs/CNAME
  3. Commit and push your changes.

  4. Open the Settings page for your Github repo.
  5. Under Source, choose master branch /docs folder. We’re basically tricking Github pages into thinking we’re a documentation project.

  6. When it rebuilds, you should be good to go.

Afterthought

It can be painful to view your solution to a problem in hindsight, given how utterly simple this all seems. I hope someone, somewhere gets some benefit from this solution.