Website Design

Updated: Jun 13, 2021

Choosing Markup Language

From my experience contributing to ILUGC website 1, I come know that Hugo 2 uses Markdown which is the most popular modern markup language in internet right now. I don’t know why but I was hesitant to go with Markdown, I searched what are the options we have. So, here are some ways to generate static html pages,

I’m not going to compare them, because I don’t know the benefits/drawbacks of each and everyone. So, I’m just giving what I felt when I tried few.

Markdown

Popular format used in everywhere. Very simple to write, literally every static site generator support Markdown. But cross referencing is pain, syntex highlighting is lacking compared to other systems, adding caption to an image is not available and there are few more drawbacks people say in internet 6.

reStructuredText

Not as popular as Markdown and not as easy as Markdown. but we can pickup easily. One of the amazing thing is to add codes and do syntex highlighting. I use lot of syntex highlighting in my blog articles. So, when I tried reStructuredText I immediately fell in love for this one amazing functionality. No wonder why reStructuredText is used by python 7, kernel 8 organizations for documentation.

Once I became comfortable with reStructuredText , I decided to go with Sphinx 9 with its default Alabaster 10 theme

RSS Feed

For a blog, having a RSS 11 feed is very important so that people who are interested in our blog will be able to get updates. Thankfully, Sphinx already have extension to generate an RSS feed file called yasfb 12,

so I simply used yasfb and integrated the output into by sidebar.

Comment System

Comments and replies are important part of a Blog. But, to write a comment in a blog post, we need to have a server to accept that comment and tag that comment with the blog post. This is impossible in a statically generated website. So, people who use static blogs choose few methods I will explain now

No comment system

Static blog owners will go with this method. They will add their blog post to either Hacker News 13 or Reddit 14 and link back those thread links into their blog post.

Comment System as Service

There are providers like Disqus 15, Facebook Comments 16 who basically will provide an embedded widget once you create account in their system. We have to embed that html widget into every article we write. This method means you have to trust the service provider.

Self Hosted Comment System

Instead of using some service like Disqus, we can also host our own Comment System like Commento 17 or Isso 18. This also requires embedding one widget in every article, but instead of communicating with some third-party provider, we can use our server with our own hosted comment system.

GitHub/GitLab issues as Comment System

With the help of GitHub 19 or GitLab 20 api, we can use GitHub/GitLab issues as comment system. Here also, we have to use one embedded HTML widget. But, instead of communicating to a third-party provider or some server which contains self hosted comment system, we use GitHub/GitLab api and use the issue system in GitHub/GitLab as comments. These type of widgets uses React 21 or Vue 22 like Front End frameworks. Few such systems are Gittalk 23 or Gitment 24.

Vssue

Gittalk or Gitment only works with GitHub, but I found Vssue 25 which works with following websites

As I’m planning to use GitLab to host my static website. I selected Vssue as my comment system

To be continued..


1

https://ilugc.in

2

https://gohugo.io/

3

https://commonmark.org/

4

https://asciidoc.org/

5

https://docutils.sourceforge.io/rst.html

6

http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

7

https://docs.python.org

8

https://www.kernel.org/doc/html/latest/

9

https://www.sphinx-doc.org/en/master/

10

https://alabaster.readthedocs.io/en/latest/

11

https://en.wikipedia.org/wiki/RSS

12

https://github.com/sphinx-contrib/yasfb

13

https://news.ycombinator.com/

14

https://www.reddit.com/

15

https://disqus.com

16

https://developers.facebook.com/docs/plugins/comments/

17

https://commento.io

18

https://posativ.org/isso/

19(1,2)

https://github.com

20(1,2)

https://gitlab.com

21

https://reactjs.org

22

https://vuejs.org

23

https://github.com/gitalk/gitalk

24

https://github.com/imsun/gitment

25

https://vssue.js.org

26

https://gitea.io/en-us/

27

https://bitbucket.org/product