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 step-by-step.
# Which Doc Tool to Use
These are what the doc tool should be:
- simple to set up
- clear doc on how to use
- big enough community to answer my questions
- 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!
Though VuePress renders beautifully and elegantly, I can't say I don't have any grudge on it:
vuepress-plugin-mathjaxrenders simple math expressions correctly, the mathjax matrix issue still hasn't been solved. So I switched to
@markspec/vuepress-plugin-katexand it works like a charm
yarn dev, it's nice that dev server automatically refresh and update the change, I still have to refresh after some changes
I've seen nice sites built w/ GitBook, but as I the why not section says, I also felt it's turning to a commercial product 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.
This doc tool is closely associated w/ React and used by many of React related projects for doc. I haven't done a React project and really wanted to have a try, but gave up b/c I haven't found a plugin for math support.
# Other Options for Doc Tool
# 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.
I tried Valine on this blog before b/c the reco-theme has a built-in plugin @vuepress-reco/vuepress-plugin-comments for comments. The placeholders default to Chinese, though users could choose English. The main reason Valine didn't make me happy was b/c I had to go over the extra steps 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?
I knew Gitalk recently and thought it's a cool idea to associate commenting w/ issues on GitHub. However, it took me quite a while to enable it. I hope the following would make your life easier.
These are the steps to initiate Gitalk on this blog:
- register an OAuth app on GitHub
- callback url is the home url
- one app for only one site/url/repo
- add Gitalk according to your static site generator
- for me, it's VuePress and I used this plugin
- 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
There are a few caveats to watch for when using Gitalk (could see my
idshould be unique and <50
titlefield is better not changed; o.w. have to the old comments on the post is lost
- better set
labelsdistinct enough to not confuse comment issues w/ real issues
- 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 to the public if I hard code them in
config.js. So I found
dotenv introduced here to hide env vars, but then Gitalk on my site doesn't work anymore!
Further, I actually read about it in Gitment README:
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
# Other Options for Comment Systems
Vssue claims to work on more than GitHub but I haven't seen many usages.