Replacing Medium with Hexo

A complete replacement for Medium with nearly zero overhead

Photo by Sky Replacement Pack on Unsplash

Recently I reached 1,000 followers, and it’s been a long journey, much longer than I thought ever.

Since a year half ago, I’ve been trying to post one article every Monday (except holidays), mainly about my work and studies, with the intention of getting more consistent exposure to attract more software engineers to discuss with me.

In this process, I found out the algorithm of the article exposure should have been drastically modified, even though the number of followers exceeded 1,000 but the number of views could be counted, and this is not even the number of reads.

This is not quite the same as what I wanted to achieve in the beginning, so I had the idea of building my own blog.

To this blog, I have several requirements.

1. To be easy to manage, I do not want to manage this site also need too much coding or operation overhead.
2. It should be easy to publish articles, the biggest advantage of Medium is it is easy to write.
3. Be able to render charts and Mermaid. My articles rely heavily on these visualizations, but right now Medium is completely incapable of doing anything with charts and Mermaid, so I have to cut and paste them from another place.
4. Be able to leave comments, this is very important, I just want to have more discussion to write articles.
5. To support clipboard uploading images, this feature of Medium is really convenient.
6. Be able to track hit rates and SEO, but the technical details of this are more complicated and not my top priority.

In the end, I chose Hexo with Github Pages as my website.

Firstly, it is quite easy to achieve this through Hexo’s built-in functions, and the generated static website is directly rendered as a Github Pages without the operation.

Secondly, after integrating Github Action, basically, after writing a Markdown file, it can be automatically published by directly pushing it to Github, which is almost the same process as writing articles on Medium.

To do the third and fourth points need to choose a good theme, I chose NexT.

For the fifth point, I used some tricks, nevertheless, I was able to do it, by using VS Code with Paste Image plugin.

This article will enable every engineer familiar with Git and open source software to build a fully functional blog in less than an hour.

Hexo + Hexo Action

About the basic usage of Hexo and Hexo Action here will not explain in detail, their official documentation is written completely.

I provide a SOP of my own, which can quickly generate a blog on Github Pages.

1. Create two repositories, one for the Hexo source code and one for the generated static website. The name of the repository for the static website must be: <username>.github.io.
2. Hexo’s source code repository just needs to git push the entire package of code after hexo init blog. Hexo has a sufficient .gitignore.
3. If you need to use Hexo Action, you need to run npm install first to generate package-lock.json, which will be used in the deployment process.
4. Generate a pair of keys for the deployment, set the private key in Hexo’s source code repository, and set the public key in the repository where the static site is located (which is still empty). For detailed process, please refer to Hexo Action’s official document.
5. Put a Github Action workflow in the Hexo source code repository, basically the example of the official Hexo Action document can be applied directly after referring to the description.
6. At this point, the two repositories are now connected properly, although the static site is not yet deployed. So we need to modify the Hexo config file: _config.yml to complete the deploy section at the bottom. For example:

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

After following the SOP, you should be able to see the static site Hexo has created at your URL, https://<username>.github.io.

NexT Theme

To install a new theme is simple, just find the theme’s Github and add it via git submodule, in this article we’ll use NexT as an example.

git submodule add https://github.com/next-theme/hexo-theme-next themes/next

That’s it.

If you want to develop locally, remember to pull the submodule.

git submodule init
git submodule update

Next, modify Hexo’s config file: _config.yml, change the default theme to next, and the theme is applied.

Then, it’s time to customize NexT.

Since Hexo 5.0.0, it supports the dedicated theme config, which is _config.[theme].yml. So we only need to copy the default NexT config file to modify it.

cp themes/next/_config.yml _config.next.yml

I only care about two functions, Mermaid and comments.

Mermaid’s settings are as follows. Just turn it on, of course, you can also modify the layout.

mermaid:
  enable: true
  # Available themes: default | dark | forest | neutral
  theme:
    light: default
    dark: dark

The comment function is more interesting, NexT supports many kinds of comment functions, including the popular Disqus and Gitalk.

But I am hosted in a public Github repository, so Disqus is directly out because Disqus requires a shortname setting, but if the shortname is obtained, it will directly cause the account breach. Many other comment functions also face the same security concerns.

Even if the Hexo source code is hosted in a private repository, as long as the static site repository used by Github Pages is public, it will still be compromised. By the way, you can pay Github to use a private repository to host Github Pages.

Therefore, the comment system needs to choose OAuth base Gitalk or Utterances, nevertheless, I don’t know why NexT needs to set Gitalk’s secret key, so Gitalk is also out.

To enable Utterances is simple as well, follow the official website process to install the OAuth App and modify the NexT config file.

utterances:
  enable: true
  repo: <installed repo>
  # Available values: pathname | url | title | og:title
  issue_term: title
  # Available values: github-light | github-dark | preferred-color-scheme | github-dark-orange | icy-dark | dark-blue | photon-dark | boxy-light
  theme: github-light

Thus, the third and fourth requirements are completed.

Uploading pictures via clipboard

To meet this requirement, we must first understand how the images are processed in Hexo.

There are two options for searching for images in Hexo:

1. Under source folder.
2. Under the asset folder, please refer to link for details.

We want to use the first way, as long as there are images under source, we can read them directly using Markdown syntax.

![](/images/abc.jpg)

In the above example, the absolute path to the image is actually <projectRoot>/source/images/abc.jpg.

But we also need a helper to read the clipboard, convert the content to image files and generate the corresponding Markdown syntax.

VS Code has a plugin, Paste Image, that makes this easy, and it can adjust the upload location and the resulting Markdown syntax accordingly. But Hexo currently places images under the source folder, which is different from the Markdown Preview plugin I currently use (Markdown Preview Enhanced).

The preview plugin is not very compatible, so I can’t get the project directory of VS Code to match the root directory of Hexo, so my VS Code project directory can only be opened under source folder as a compromise.

This makes the Paste Image settings need to be adjusted accordingly. Here are the settings I use, at <projectRoot>/source/.vsconde/settings.json.

{
  "pasteImage.basePath": "${projectRoot}",
  "pasteImage.path": "${projectRoot}/images/",
  "pasteImage.prefix": "/"
}

The reason for this compromise is I need the Mermaid preview feature of Markdown Preview Enhanced. Until I find another way to do it, this compromise is a doable solution.

The good thing is that my writing process is not affected. When I need to publish an article, I just add a new Markdown to my VS Code project path, push it to Github after writing, and then it will be automatically deployed, so it doesn’t matter if the VS Code project path is source.

Conclusion

By combining these following components, it allows me to write articles in a more efficient way than Medium, and the previous pain points of having to cut and paste Mermaid and tables have disappeared.

• Hexo
• Github Action
• Github Pages
• NexT

In addition, there is more room for customization, which is the best solution at the moment.

Currently, my audiences are divided into English and Chinese circles, and Medium’s exposure to Chinese articles is lower than English, so I will gradually adjust the posting frequency and content in the future. After that, I will adjust my posting strategy based on the tracking data I collect.

My main profession is a data architect, so this is my experiment with Medium and the blog I own.