by Andrew Akagawa
You’re an entrepreneurial nerd. You just finished your minimum viable million dollar app and launched. Now time to sit back and watch the viral onslaught of users roll in. One problem… nobody knows you exist.
Ya, you’ve heard it all before, the spiel about content, content, content, but never took it seriously. Who has time for that when you’re developing a product? But now you finally get it… You need a blog.
We’ll be launching this as a static site on github pages so that you’ll be able to get your blog going for free. The following are what we will use. If these look foreign to you, then you may want to try Wordpress, or I’ll also plan to write tutorials on these, so stay tuned and subscribe.
- A GitHub account
- A linux style operating system
Let’s get started by making your blog directory. I’m calling it blog, but name it whatever you like.
Open your blog directory and install Hexo.
If you get a permission error, try:
Now let’s get hexo started by running the following command:
Great! Now you have all the hexo files to get started. Next, let’s get GitHub setup to host your site.
Go to GitHub.com, and login or signup.
After, you should see a screen like this:
Click “Start a project”.
Github will allow you to host your site for free. In order to do that, you must name you repo the same as your username followed by .github.io. See example below for submithealth but replace with your username:
Click “Create repository”
Make note of your git url. Mine is as follows, but yours will look a bit different:
Now head back to the blog directory you created. Initialize git and add your url as a remote origin. Be sure to swap the example git url below with your git url.
Next, you’ll need a text editor. If you already have one fell free to use it. If not, I like using nano, which you can install by running the following command:
You should have a file in your directory named _ config.yml . This file is the sort of backbone of your blog, and holds a lot of config settings. Open with nano or your favorite text editor.
You can play around with this file, but we’ll skip right down to the deployment section so we can get ready to publish to our github hosted page. Find the deploy section in this file and edit it to reflect git as type and your git url as repo. (Note, be sure to swap the example url below with your actual git url):
Save your file.
Now you’re ready to make your first deploy. Hexo has built in commands to make your blog framework. The generate command gets all your files ready, and the deploy command will publish them to github. The files published will not be the same as the files in your git repo, so no need to run a git push to github.
First install the git deployer:
Next run the following commands:
Navigate to your new website. Your site should be hosted at a url that is your username followed by .github.io. For me it is submithealth.github.io.
Great! You have a framework up and running. Now you’ll want to make your blog really yours. I won’t get into the details with this as there are several helpful resources out there already, but I will give a quick overview and thoughts on where to go from here.
There are lot’s of great themes that exist for Hexo. You can browse them here. They generally have great documentation covering installation and customization. A few quick things I’ll note about how the infrastructure works. After installing a theme, you will specify the theme you are using in your _ config.yml file. The associated theme’s files and folders will be installed in your /themes directory. Each theme will have its own separate _ config.yml file, with its own set of options for how to customize and add features to your site.
You can create new posts by entering the following:
Your posts will be in markdown format. If you’ve never worked with that, it’s basically a super easy, shorthand way of writing html. Here’s a great cheat sheet to help you get started, thanks to Adam-P.
Your posts will be in your _ /source/posts directory, which you can open and edit with nano or your preferred text editor. When you are ready to deploy, run the generate and deploy commands again:
Remember, this is not a typical git push, which kind of confused me at first as I was trying to push my repo and was wondering why my site wasn’t working. You have to run the generate and deploy commands, and Hexo runs a script to put your posts and files in the right directories and automatically pushes to your hosted website.
Work with your DNS provider to have your domain or subdomain CNAME record point to your github url (your username followed by .github.io). If what I just wrote looks confusing, you can also always just call or message your domain provider and say “Hey DNS provider… update my CNAME to point to this github url.”
Finally, setting up the domain on github was not entirely straightforward to me. Don’t set this up on your repo settings on the Github website as hexo will just overwrite this with every deploy. Here’s what I think is the easiest way to do this. From your blog directory, move into your public directory and create a file named CNAME :
Now, simply enter your desired domain or subdomain on the first line and save. For me, it’s as follows:
Now deploy your site, and you should be up and running on your domain:
Thanks for reading, and hoped this helped in getting your blog setup! Thank you to Hexo for making an awesome framework, and to Github for hosting it, and check out the documentation here to keep you running.