Hello World, and building your own blog

ProgrammingHexo
blog, git, github, hexo, markdown, node, npm

Hi ! I’m Aurélien, but you’ll find me around on the web as Kyne, or KyneSilverhide. I’m a developer from Belgium (yes, we have beer and chocolate).

I’ve recently learned about Hexo, a very powerful tool to build “static blogs”, using Markdown and some command lines. As most developers should know, the best way to test or learn something is by using it in a real project. That’s why I’ve decided to start this blog mostly about programming stuff, and technologies.

In this very first post, I’ll show you how to install Hexo for you own blog, and host it on Github (for free, of course).
Also, English is not my main language, so I hope everything will be as smooth as possible.

Github

Create your account

Any developer should already know about Github. Basically, it will host your source code for free, and keep an history of changes using a version control system called Git (we may talk about this later…). Fortunately, you don’t need to know GIT in this case, because Hexo has already automated everything for you, so you can focus on writing content.
So, head over to https://github.com/, create an account, and we’ll meet again in the next section.

Creating your first repository

Once your account is created, we’ll create a repository to store our website. But we won’t build a basic repository. Instead, we’ll use a “new” functionality from Github called Githut Pages. I won’t go into the details, but this will allow your blog (or website) to be accessible at “http://username.github.io“. As long as you only hosts static pages and assets (javascript, css, pictures…), everything is taken care of.

Your repository must be called “username.github.io” (where username is your github username). From my experience, it’s seems case-insensitive.
Once created, we’ll need to download it on your computer. And to achieve that, we need to install Git.

Once Git is installed, open a terminal (or Git-Bash on windows), and go to your workspace (If you don’t have one, just pick a folder somewhere on your computer)

1
2
3
 
cd /path/to/my/workspace
git clone https://github.com/username/username.github.io
cd username.github.io

(don’t forget to replace “username” with your github username)

Using any text editor or IDE, create a new file called index.html inside the newly created folder, and fill it with anything your want (as long as it’s valid HTML.. of course)

1
2
 
<h1>Hello World<h1>
This is my website hosted on Github pages

And then, in order to publish everything on Github, we’ll need to type some GIT commands. Don’t worry, it’s the only time.

1
2
3
 
git add --all
git commit -m "Initial commit"
git push -u origin master

If you have already worked with any other VCS (Version Control System), these commands may look familiar. The main difference between Git and SVN or CVS is that you first have to “commit” your changes to a local repository, and then “push” everything to the remote server.

You should now be able to access your website in your favorite web browser by accessing this URL : http://username.github.io

Hexo

Installing Node and NPM

Ok, if you are still reading this, let’s continue with Node and NPM. NPM is nothing more than a package manager. It will help you install program, libraries, etc.. and handle dependencies.

Go to https://nodejs.org/en/download/ and choose the proper installer for your operating system (Node comes with NPM installed). If you are using windows, you should continue using Git-Bash as your terminal (it emulates some features from Unix-based terminals). Cmder is another great terminal on Windows that you may consider using for this tutorial.

Installing Hexo

Once Node is installed, let’s finally start installing Hexo. (On UNIX environments, you will need to run this command as the administrator)

1
 
npm install hexo-cli -g

Now, somewhere in your workspace, let’s setup a new folder that will contain your blog

1
2
3
4
 
cd /path/to/my/workspace
hexo init blog
cd blog
npm install

Configuring the blog

The first step is to change the basic configuration defined in _config.yml (by the way, .yml files, for YAML, are just plain text files using indentation to define the structure. With XML and JSON, these are the main formats for configuration files)

1
2
3
4
5
6
7
8
9
10
11
 
title: My awesome blog
subtitle: Made with Hexo
description: Some more text
author: KyneSilverhide
language: en
timezone: Europe/Brussels
url: http://username.github.io
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:

Everything else can be left with the default values.

Creating a post

Save the configuration file, and go back to the terminal. Let’s write our first post.

1
 
hexo new post "My first post"

All your posts are created inside the source/_posts folder. Open the .md file (for Markdown) matching your post title, and edit it.

1
2
3
4
5
6
7
 
---
title: My first post
date: 2016-11-26 14:27:16
tags: [blog]
categories: [Blog]
---
This is my first post ! I'm so happy.

Note : some themes may allow additional elements, such as a thumbnail, a banner, etc.
Tags and categories may not be shown depending on your theme, but it seems to be a good practice to fill them. If you want to add multiple tags or categories, just put a , between each.

Ok, now that we have some content, we want to preview it before deploying everything to Github. But if you remember right, Hexo is a tool used to build static blogs. This means we have to “build” our site first, using this simple command : 

1
 
hexo generate

You’ll see some files being created or updated, and then you are done. Now, let’s see a preview. Another great feature with Hexo, is that you don’t need to setup a web server such as Apache. You just have to run this command :

1
2
3
4
 
hexo server
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/. Press Ctrl+C to stop.

Open the given url http://localhost:4000 in your browser, and you should see your first post !

If you want to know more about the Markdown syntax that you can use in your posts, just head over to this Markdown CheatSheet.
This syntax can also be used in some Wikis and other tools.

Publishing it to Github

If everything works fine, it’s time to show your blog to the world. Let’s start by some configuration. Open _config.yml, and change this part

1
2
3
4
 
deploy:
  type: git
  repository: https://github.com/username/username.github.io.git
  branch: master

Of course, you have to change “username” with your Github account.
Don’t forget that you need to generate your blog content before deploying it. You have three options

Manually generating and then deploying

1
2
 
hexo generate
hexo deploy

Using any of these two shortcuts

1
 
hexo generate --deploy
 

1
 
hexo deploy --generate

During the deployment, you’ll be asked for your Github login and password. Fill them in, and the deployment process should continue.
This will also remove the test index.html that we wrote at the beginning of this tutorial. Don’t worry, we won’t need it anymore.

Your blog should now be accessible at http://username.github.io. Congratulations !

Conclusion

Now that we have do so many awesome things (yes, auto-congratulation is very important as a developer), let’s take a step back and list what we have accomplished today.

  • First, we have created a Github account to host our blog. But Github is also one of the best solution to host the source code of all your projects, so feel free to check their website.
  • Then, we use some Git commands to send our test page to Github. Git is also a very famous tool (and my favorite VCS), but it can be hard to master, so I only scratched the surface in this blog. You should find some more tutorials on Github, or around the web.
  • After this, we installed Node and NPM. If you are a web developer, you should already have these installed. There are so many libraries, projects and applications built on top of node, and available through NPM. But be aware that NPM seems to download the whole Internet each time you use it.
  • The next step was to Install Hexo, and write some content. If you want to continue your blog, I recommend you to browse some of the Hexo Themes, learn more about Markdown, or read the Hexo Documentation
  • Lastly, we published our blog to Github. Feel free to test it on your tablet or mobile phone too !

This concludes my first post. I hope that this tutorial have taught you something, or helped you somehow, and we’ll meet again in the next post !

Share Comments