Ziyuan Qin's blog

About Algo

2/23/2020 whoami

Recently, I created the algo site to record algorithm problems I've solved.

I've encountered many weird errors but also learned so much in the process!

When I migrated my blog from Jekyll to VuePress, it also took me a few days to figure out how to use the reco-theme, such as updating frontmatter w/ categories and adding a sidebar. When I created the algo site this time, reco-theme no longer applies b/c it's designed for blogs while I was creating a doc. This forced me to abandon laziness (temporarily 😛) and start from scratch by following the offical VuePress doc (opens new window) step-by-step.

# Which Doc Tool to Use

These are what the doc tool should be:

  1. simple to set up
  2. clear doc on how to use
  3. big enough community to answer my questions
  4. good math support

Initially, I didn't want to choose VuePress for the algo site b/c I've alreay used it for the blog and wanted to try sth new.

I did a lot of research on quite a few alternatives before I made my mind to keep using VuePress and hone my skills in Vue!

# VuePress (opens new window)

Though VuePress renders beautifully and elegantly, I can't say I don't have any grudge on it:

  1. though vuepress-plugin-mathjax renders simple math expressions correctly, the mathjax matrix issue (opens new window) still hasn't been solved. So I switched to @markspec/vuepress-plugin-katex and it works like a charm
  2. after yarn dev, it's nice that dev server automatically refresh and update the change, I still have to refresh after some changes

# GitBook (opens new window)

I've seen nice sites built w/ GitBook, but as I the why not section (opens new window) says, I also felt it's turning to a commercial product (opens new window) nowadays. In terms of "slow development reload performance w/ a large amount of files", I can't speak of that per se. Anyway, I want to go for a free option.

# Docusaurus (opens new window)

This doc tool is closely associated w/ React.js (opens new window) and used by many of React related projects for doc. I love React but not so much this tool.

# Other Options for Doc Tool

I didn't look too much into other options such as Storybook (opens new window) and Docz (opens new window) b/c the former looks too dazzling and the latter not appealing in style.

# Comment System

Gradually, I think having people from the globe discussing on a common topic is a cool idea rather than a distraction. I hope the comment system is simple, straightfoward, but has some authentication to prevent random chit-chat.

# Valine

I tried Valine (opens new window) on this blog before b/c the reco-theme has a built-in plugin @vuepress-reco/vuepress-plugin-comments (opens new window) for comments. The placeholders default to Chinese, though users could choose English (opens new window). The main reason Valine didn't make me happy was b/c I had to go over the extra steps (opens new window) to enable email notification after a user responds. This took me half a day but still finally failed.

Also, Valine is developed by LeanCloud, who is a freemium SaaS provider. Why do I need to watch for not being charged and going thru all the hassle to enable email responding system?

# Gitalk (opens new window)

I knew Gitalk recently and thought it's a cool idea to associate commenting w/ issues on GitHub (opens new window). However, it took me quite a while to enable it. I hope the following would make your life easier.

# Steps

These are the steps to initiate Gitalk on this blog:

  1. register an OAuth app on GitHub
    • callback url is the home url
    • one app for only one site/url/repo
  2. add Gitalk according to your static site generator
  3. push & debug
    • coz it's hard to succeed in first trial
    • note that the home & callback url's are in prod, so dev server would redirect to prod url's

# Caveats

There are a few caveats to watch for when using Gitalk (could see my config.js (opens new window)):

  1. id should be unique and <50<50 chars
  2. title field is better not changed; otherwise have to the old comments on the post is lost
  3. better set title and labels distinct enough to not confuse comment issues w/ real issues
  4. YOU have to go to the post in prod to initiate comments just on that page

# Hide Secrets, or Not

After I made Gitalk work on my site, I was worry about leaking my client ID and secret in hardcoded in config.js (opens new window) to the public if I hard code them in config.js (opens new window). So I found dotenv introduced here (opens new window) to hide env vars, but then Gitalk on my site doesn't work anymore because Github servers don't have my local env vars in .env!

Further, I found the following in Gitment README (opens new window):

Although GitHub does't recommend to hard code client secret in the frontend, you can still do that because GitHub will verify your callback URL. In theory, no one else can use your secret except your site.

Thus, at least in this case, hardcoding 2 env vars is alright, and I reverted back and uninstalled dotenv.

# Other Options for Comment Systems

Gitment (opens new window) is quite similar to Gitalk (opens new window) but supports likes.

Vssue (opens new window) claims to work on more than GitHub but I haven't seen many usages.