Using own domain with github and hexo

I’m assuming the following:

  • You are using Hexo
  • Your blog source (posts written in markdown, themes, configuration files etc.) is in branch called source (or some other branch than master). This keeps things simple as the source branch contains the raw material and master branch has the current version of the blog.
  • You host your blog in github under username.github.io repository (replace username with your github username). See GitHub Pages for more information.
  • You can push changes to github (both master and source branches).
  • You have your own domain.

During this guide we are always in the source branch. There is no need to checkout master branch.

Start from clean slate

Stop hexo server if it is running on your local machine and use hexo clean to remove all generated files.

1
2
3
4
5
6
$ hexo server
INFO Hexo is running at http://0.0.0.0:4000/. Press Ctrl+C to stop.
INFO See you again
$ hexo clean
INFO Deleted database.
INFO Deleted public folder.

Add your domain into hexo

Modify the url in _config.yml to look like the following. Replace mydomain.com with your own domain and remember to save the file.

1
2
3
# URL
url: http://mydomain.com
root: /

Set up hexo-geployer-git

Install the hexo-deployer-git package.

1
2
3
4
5
6
7
8
$ npm install hexo-deployer-git --save
npm WARN optional dep failed, continuing fsevents@0.3.6
hexo-deployer-git@0.0.4 node_modules\hexo-deployer-git
├── chalk@0.5.1
├── moment@2.10.3
├── hexo-util@0.1.7
├── hexo-fs@0.1.3
└── swig@1.4.2

Note fsevents is for Mac OS X so if you are using other operating system you can ignore the warning.

Configure git deployment by adding following into _config.yml and saving the file. Replace username with your github username.

1
2
3
4
5
6
# Deployment
## Docs: http://hexo.io/docs/deployment.html
deploy:
type: git
repo: git@github.com:username/username.github.io.git
branch: master

CNAME file

Github uses file called CNAME to redirect your site. If you read the official guide it says the file must saved under the root directory in the master branch. But remember that for us the source branch is where the raw material is and master branch is generated when you deploy. So if you put something in the master branch it will be overwritten next time you deploy your site.

Create file called CNAME (all caps, no extension) under the source directory in the source branch and write your domain name into that file. Replace mydomain.com with your own domain.

1
2
3
4
$ cd source/
$ echo mydomain.com > CNAME
git add CNAME
git commit -m "CNAME file for domain"

Configure DNS settings

The following instructions are for namecheap but the settings (A record, CNAME) are pretty universal. Login to namecheap, select your domain and go to All Host Records. Fill in the A record and CNAME as seen in the following picture. Remember to replace my repository address with your own and don’t forget to add the trailing dot (username.github.io.).

Namecheap DNS settings

I’m using ip address 192.30.252.153. You can double check it from the GitHub’s tips for configuring an A record guide. Note the TTL (time to live). If you are changing your existing domain to point to github you might have to wait for a while before the settings have propagated to other domain name servers.

Generate blog

1
2
3
4
$ hexo generate
INFO Files loaded in 547 ms
INFO Generated: CNAME
INFO 543 files generated in 1.02 s

Deploy to github

1
2
3
4
5
6
7
$ hexo deploy
INFO Deploying: git
INFO Setting up Git deployment...
Initialized empty Git repository in .deploy_git/.git/
INFO Clearing .deploy folder...
INFO Copying files from public folder...
INFO Deploy done: git

If you cannot access your domain

Check that the domain has been correctly configured by browsing to your repository username.github.io repository and clicking the settings link.

GitHub repository settings

In the settings under GitHub Pages you should see that the domain has been correctly configured.

GitHub Pages settings

Remember to check your domain settings from your domain provider.

Finally

Commit and push the changes you have made in the source branch.