Website Design

Updated: May 07, 2024

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..