Blogging Data Science Projects with Hexo

6 min readOct 28, 2018

Thinking of blogging on your website for data science projects but having no idea how to start? Don’t worry. Here is a quick-start guide I will walk you through. In the end, you’ll have a blog deployed to your GitHub Pages. The development process will familiarize you with Hexo static site generator to build up your personalized website.

A minor heads-up: if the computer operating system of your machine is not Windows, you need to accommodate the steps listed below to your specific system on your own. I focus on the command-line installation on Windows through the Command Prompt.

Preparation

Before embarking on your installation, check to see if you have the following programs installed or accounts at hand:

Anaconda Python. Be sure to add Anaconda to your PATH environment variable.
Jupyter, a Python package for interactive computing.
nbconvert, a Python package for converting Jupyter notebook to markdown files.
Git for Windows. Be sure to generate a SSH key and add it to the ssh-agent. If you have done this before, see this instruction.
GitHub account. If you don’t have a GitHub account, go here to get a free one. Sign in your account and create a new repository (at this link). Enter <your-github-username>.github.io into the box under “Repository name.” Suppose your username is “JohnDoe”, the repo name should be JohnDoe.github.io. You can leave others unspecified and leave the web page by clicking “Create repository.”
Node.js and NPM. Here is the installation guide of Node.
Hexo. To install it, in the Command Prompt (hereafter, CMD) enter > npm install hexo-cli -g. Be noted that throughout this quick-start guide, each command-line commands is preceded by a > symbol led by a directory string. You will ignore them as you type commands into your own machine.

Building your blog on disk

Before deploying your blog to the Internet, build it up on local machine first. Suppose you are at the directory C:\ in CMD and want to create a folder named “blog” as a repository (in short, repo) to host local website files. To initiate the functions of Hexo, enter the following commands:

C:\> hexo init blog
C:\> cd blog
C:\blog> npm install

You should see a welcome message like “INFO Start blogging with Hexo!” For having a feel of how the newly-generated website in its pristine mode looks like, we create a new post file named “JohnDoe” by entering:

C:\blog> hexo new "JohnDoe"
C:\blog> cd source\_posts
C:\blog\source\_posts> echo "this is new." >> JohnDoe.md
C:\blog\source\_posts> hexo server

Open your favorite browser and key in http://localhost:4000. You should see two posts shown: the one on the top “JohnDoe” is what you just created with the content “this is new”. The other is the default Hello World post that comes with the blog initialization.

At this point, your blog web site is premature in the sense that its appearance has not been specified in accordance with your personal taste. You can browse here for favorite theme in the theme gallery and learn how to change your blog theme.

Here is a glimpse of the specification in _config.yml , the configuration file of your main web site. It is located in the directory “C:\blog” in my case.

title: Titanic
subtitle: a 1997 American romance film
description:
keywords:
author: Leonardo Dicaprio
language: en
timezone:

See here for a simple tutorial on the configuration of Hexo-generated website. I’ll talk about this topic more below.

Blogging Jupyter notebooks

Method 1.

Suppose you like to blog a Jupyter notebook named, “jupyter.ipynb.” Copy this file and save it to the directory “C:\blog\source\_post” before entering:

C:\blog\source\_post> jupyter nbconvert --to markdown jupyter.ipynb

A markdown file, “jupyter.md,” is generated in the same directory.

Edit “jupyter.md” with a text editor to set up this markdown file’s front-matter (Front-matter is metadata used by Hexo and the active theme. See the here for more information). In the first line of the file, insert the following template with appropriate substitution:

---
title: “My first iPython Notebook post”
date: 2018–10–24 00:35:13
---

Enable the Hexo server by entering into CMD and entering C:\blog> hexo s. After that you should see the rendering of your Jupyter notebook at http://localhost:4000.

If you find the object spacing is larger than expected, navigate to the blog’s configuration file _config.yml and insert the following code in the end:

marked:
 gfm: true
 breaks: false

The expected rendering of the converted markdown file should be similar to the following sample output:

Method 2.

Install Hexo pacakge hexo-jupyter-notebook and a module it depends:

> npm install hexo-jupyter-notebook — save
> npm install co

The --save option instructed NPM to include the package inside of the dependencies section of your package.json automatically, thus saving you an additional step.
Install pandoc either through its installer or via conda.
Check whether the Python package nbconvert is installed.
Enable post asset by adding this line in your blog’s _config.yml:

post_asset_folder: true

To make the example trickier, suppose that the Jupyter notebook file, “test.ipynb”, is stored in the path, C:\blog\source\_posts\ipynb and your goal is to convert the file to markdown format and save it in the path C:\blog\source\_posts.

a. Generate a new post, say, hexo new jupyter.

b. A markdown file named “jupyter” should be generated.

c. Edit jupyter.md:

---
title: jupyter
date: 2018-10-27 19:57:55
tags:
---
Some content before the snippet......<script src="http://code.jquery.com/jquery-2.0.0.js"></script>
{% asset_jupyter C://Users//usename//Anaconda3//python ..//ipynb-source//test.ipynb %}Other content after the snippet.......

The template should be kept in your own applications except for the directory of Python.exe and the path to the Jupyter notebook.

You should see the Jupyter notebook post locally again by running > hexo s.

To adjust the rendering style, edit main.py in the hexo-jupyter-book folder in the directory C:\blog\ node_modules.

<iframe id='ipynb' marginheight="0" frameborder="0" width='924px' height='680px' srcdoc="%s" style="scrolling:no;">
</iframe>

The expected result should look different from what we obtain using method 1. Here is a sample output:

Deploying blog to GitHub

First, enter the following command into CMD:

C:\blog> npm install hexo-deployer-git --save

Second, open the configuration file of your blog _config.yml , which is located at the root directory of the blog. In my case, C:\blog. Specify the parameters under the deploy section by following this template (Be sure to replace <github-username> with your real GitHub username):

deploy:
 type: git
 repository: git@github.com:<github-username>/<github-username>.github.io.git
 branch: master

Enter the following thing into CMD:

C:\blog> git remote add origin git@github.com:<github-username>/<github-username>.git

If you have successfully saved your public SSH key into your GitHub account (tutorial) and have set your Git username and email (tutorial), you will see no error message.

C:\blog> hexo d -g

Now you can see your post at https://<github-username>.github.io/.

Conclusion

I established my first blog website in half a day (click this link for the update of my blog) by googling the information and some trial-and-error efforts. I further associated the Hexo blog with my old WordPress home page i.e., I had my blog be the redirected target of my front page. By doing so, I can blog my technical posts on my old WordPress homepage without worrying about the WordPress’s limit in handling graphical data science results and the accompanied code snippets. Sounds fantastic, right? Go create one for yourself and let me know if you have any questions.