Create a markdown blog in 10min using Hexo (Part 1)

Like a lot of people, I’ve always wanted to create a blog and start writing, but never had “enough time”… 😴

Yesterday, an idea came to me: I’m a developer, I use Markdown every day to take notes and create documentations for things I develop/build. Why wouldn’t I use markdown to write a blog?

In this article, which is my first blog post, I’ll explain how I built and deployed this article… ⚠️ Infinite loop ⚠️

Why markdown (MD)?

First, let’s talk about Markdown, what it is, and why I decided to use it.

Markdown is a lightweight but powerful markup language. It’s really easy to write and format plain text articles/documentation, thanks to its simple formatting syntax. You just need to “mark” your text with symbols like hashtags, wildcards, bracket symbols to create titles, lists, hyperlinks…

For non-developers, following is a small example of some text, formatted with markdown.

1
2
3
# "#" means this is a level-1 title
## "##" means this is a level-2 title
here goes a paragraph...

Here is a link to a useful markdown cheatsheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

VS Code

To write, edit and preview my markdown files (.md), I use Visual Studio Code. I also develop some of my apps with VS code, which is very convenient.

Create a blog with Hexo

Hexo?

When this idea came to me, I was super excited about developing an app that would generate some blog posts for me from markdown files. But wait… Let’s search for “Markdown blog” on Google first 🧐

Here you go! 2nd result on Google: Hexo.io, “A fast, simple & powerful blog framework”.

Hexo website screenshot

All right, I don’t need to develop it and the good news are it’s an npm module! All the keywords I was searching for are on this page: Markdown, NPM, Easy Deployment. I already love it 😎

Install Hexo and start it

I assume you already have Node.js and NPM installed.

Let’s run the commands hexo.io tells us to run.

1
2
3
4
5
npm install hexo-cli -g # add "sudo" if required
hexo init blog # rename "blog" with your blog name, mine was nanblog
cd blog # go to the directory
npm install # install the npm packages/dependencies
hexo server # start a local webserver

Great! We’ve just created our blog 🎉, let’s configure it now.

Customize our blog

The file _config.yml contains some parameters for our blog, as the name suggests.

Themes

Let’s be honest, the default theme is… not the most beautiful theme I’ve ever seen 🤢

Got to https://hexo.io/themes/ and download the theme of your choice into the “themes” folder. For instance, I’ve downloaded the Cactus theme under themes/cactus.

Then, I just had to edit the _config.yml file to select cactus as my theme.

1
theme: cactus

Don’t forget to read the README file of the theme you’ve downloaded, you’ll probably need to configure the theme’s _config.yml file.

Create a draft or a post

To create a new post, hexo offers some simple commands:

1
2
3
4
5
# create a new draft
hexo new draft "my new draft post"

# create a new post
hexo new post "my new post"

The difference between a draft and a post is quite obvious, a post will be immediately published, a draft won’t.

Then, just open the source/_posts/my-new-post.md file and edit your markdown post.

Once you’ve written a draft and it’s ready to go live, all you need to do is to run the following command:

1
2
# create a new draft
hexo publish my-new-post.md # my-new-post is the name of your draft file.

It will automatically convert the draft to a post, ready to be published 😀

You don’t necessarily need to create a draft before promoting it as a post if you plan to publish it immediately. But I guess it’s a best practice.

Note that you won’t be able to see your drafts in the local website served by our local server. To see it locally, you need to add one more option to the server command.

1
hexo server --draft

Deploy the blog on GitHub pages

GitHub pages is a simple way to host a basic (static) website for free. No database needed.

First, create a new repository on GitHub, name it “yourusername.github.io”. For example, mine was nicolasanjoran.github.io. Make sure it’s a public repository.

Deploy key

You’ll also need to create a “Deploy key” to be able to deploy the generated code to GitHub. You can skip this step if you already use GitHub and already have some SSH keys setup on your GitHub account. Following are the basic steps, please go to the GitHub Help for more details.

1
2
3
4
5
6
7
8
# Generate a new SSH key
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Start the SSH key to the ssh-agent
eval "$(ssh-agent -s)"

# Add the key to the agent
ssh-add -K ~/.ssh/id_rsa

GitHub also warns us:

If you’re using macOS Sierra 10.12.2 or later, you will need to modify your ~/.ssh/config file to automatically load keys into the ssh-agent and store passphrases in your keychain.

1
2
3
4
Host *
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_rsa

Then, copy/paste the contents of the generated key in the GitHub deployment keys section.

Test our GitHub page

Before deploying my blog to GitHub pages, I’ve just uploaded a very simple “Hello world” HTML page to the repository and just opened http://yourusernamegithub.io to check that the URL points to my GitHub repository 👌.

Update our config file

To get our blog deployed on GitHub pages, we need to update our _config file, just add the following yaml parameters to the _config.yml file.

1
2
3
4
5
6
7
# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
type: git
repo: git@github.com:yourusername/yourusername.github.io.git
branch: master
message: "Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}"

Deploy

Hexo offers multiple deployment systems, I decided to deploy my blog on GitHub, bug you can deploy yours on Heroku or even using Netlify or Rsync… See the full list of deployment types here.

To use the git deployment, we need to install the hexo-deployer-git module.

1
npm install hexo-deployer-git --save

Once it’s installed, we will deploy our blog. The hexo-deployer-git will create a commit with the message we’ve specified in the config file. This commit will be automatically created and pushed on GitHub using the deploy command.

1
2
3
4
5
# Generate static files
hexo generate

# Deploy the blog
hexo deploy

Let’s Go! Our blog is now up and running at http://yourusername.github.io 😎🥳

What’s next?

  • Add a custom domain, instead of the .github.io domain.
  • Setup a live-reload server locally
  • Use multiple git branches to manage our blog
  • Maybe, customize the theme

I’ll upload a part 2 of this article to cover at least some of those topics! 🤗