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 ⚠️
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.
# "#" means this is a level-1 title
Here is a link to a useful markdown cheatsheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
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.
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”.
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 😎
I assume you already have Node.js and NPM installed.
Let’s run the commands hexo.io tells us to run.
npm install hexo-cli -g # add "sudo" if required
Great! We’ve just created our blog 🎉, let’s configure it now.
The file _config.yml contains some parameters for our blog, as the name suggests.
Let’s be honest, the default theme is… not the most beautiful theme I’ve ever seen 🤢
Then, I just had to edit the _config.yml file to select cactus as my theme.
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.
To create a new post, hexo offers some simple commands:
# create a new draft
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:
# create a new draft
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.
hexo server --draft
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.
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.
# Generate a new SSH key
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.
Then, copy/paste the contents of the generated key in the GitHub deployment keys section.
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 👌.
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.
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.
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.
# Generate static files
Let’s Go! Our blog is now up and running at http://yourusername.github.io 😎🥳
- 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! 🤗