Just rewritten my blog site (again!)

JAMstack and the Diversity of Static Site Generators (SSGs)

I discovered Jekyll when I was experimenting with GitHub and I found about Github pages when I was thinking about making my own blog. I gave up on that, since I was relatively new to programming in general, and I don’t know Ruby.

Then I moved to Gitlab because of the ‘Microsoft buying Github’ fiasco^{† †} I’m not really know why; I’m just a really impressionable teenager back then. I still have my Github account, but I do a lot of git stuff in Gitlab nowadays. . Gitlab has a Github equivalent called Gitlab Pages. Not creative naming, I know. Gitlab has a repository full of templates for different SSGs like Pelican, Jekyll, Hugo, and etc. I chose Pelican because the only programming language I know of is Python, and Pelican -> written in Python -> easy to customize!

It isn’t easy to customize. I basically “installed” a theme, and “installed” I mean “copied from a repository full of themes and pasted it in my folder.” Now, I was afraid of changing things to my liking due to the fact that the code was not mine. Every time I tried to change something the design of the website would break, and thus I could add my own features that wanted.

Fast forward to the middle of pandemic. I was dabbling with Rust, because setting up C was confusing to me and I don’t like my experience with it when writing programs for my Arduino. Through that I found out about Zola. When I first used it I found it liberating since now I don’t really need to copy a theme. As an 18 year old back then I had now more experience in CSS and Javascript, and now I have a necessary tools to create my own design. So I did my own design, and it was passable, despite the lack of knowledge in the passing trends of the web development lifecycle.

It isn’t enough, as I fear. There are times that I would like to use frameworks that needed things like just-in-time compiler and Javascript technologies. Bootstrap-like frameworks are becoming more and more obsolete in favor of lighter alternatives like TailwindCSS. And so Zola is becoming not enough for me, as integrating Node into the build script is hard, especially when third party services holdhand you to deploying your own website automatically without much configuration.

And so I went searching. And I found about JAMStack.

Javascript SSGs are bloated (but I want their features)

The JAM in JAMStack means:

• Javascript
• API
• Markup

There are long explanations for implementing the JAMStack, so I’ll just redirect you to the definitive website. Basically, instead of a traditional website where you make server that interfaces with databases and CMS and serves on the web, you just serve a site generated by an SSG that connects to a CDN and a bunch of microservices.

This reduces the amount code needed to write a website, especially for those that do not need an advance server to process user input.

I’m sold the moment I read and understood the concept. Who wouldn’t want a less bloated web.

The problem right now is the abundance of Javascript SSGs that are outright heavy for the web.

You see, the majority of these SSGs are built using React and Vue. In the JAMstack website, seven out of the top ten sorted by Github stars are written in full React or Vue. This poses a problem for me, as both of these Javascript frameworks actually make the entirety of your website reliant on Javascript. One of my goals is to make my blog a little bit privacy friendly, and I do not want my blog to be broken just because people disabled Javascript on their browser.

So I do not want my website fully be in Javascript.

That doesn’t mean I do not want to use client Javascript in my website.

There are cases that needs Javascript to work, like that hamburger button you see at the top. That’s why I included something like the sitemap at the bottom, for accessibility.

Ah yes. Accessibility.

I would admit that accessibility is relatively a new concept to me, as I realized that: as a person whose hearing gets a bit… bad as time goes by, accessibility is really important. I want my content to be accessible and enjoy by everyone.

So I can’t use React and Vue. But I don’t want to use something like Jinja2 or Tera, because that means that I’m going back to the original, and there’s no point in doing that.

Essentially, I want to have the flexibility of React/Vue without the bloat that comes with it.

And Astro came along.

My thoughts on Astro

I forgot how exactly I found out about Astro, but when read the website, I was hooked. An actual SSG that strips unnecessary Javascript? I’m in!

However, that time (I think it was around August/September?), Astro was v0.20. The first time I used it, I felt like it was lackluster, maybe due to the fact that the documentation is not yet complete. Specifically, markdown in Astro didn’t support custom components just like in MDX style markdown. Also, I was considering whether or not I should use a Content Management System (CMS). A lot of factors went in making a website, and since my academic life was getting busier, I put the idea back in the shelf.

Now, with the release of Astro v0.21 and TailwindCSS 3.0.0, I thought to myself, “maybe it’s time to redesign my website once again!”^{† †} And yes I did! You’re seeing it right now. There are some thing I would like to improve upon, so if you see any bugs, please create an issue at the Gitlab project page.

With my current experience with the SSG, I think Astro is right for my needs. I love the system of layouts and components, it’s similar to Zola’s templates and shortcodes.

I also like the concept of partial hydration. When I first started reading about JS SSGs, they keep going on about hydration. Turns out, it’s a term for simply turning a static web page to a dynamic one through hooking event handlers onto HTML elements¹. I personally think that the less client-side Javascript there are in a web page, the less bloat it will have, and the better performance and footprint it will have on the world wide web.

Moving on. I know that Astro is currently at it infancy right, and as such, it lacks proper features that would make it a fully fledged static site generator. However, I plainly do not know how the Javascript ecosystem works, and its new version uses Vite, which is the first time I’ve heard of something like this. I don’t even know what it does. Is it simply a build tool? I don’t know.

TailwindCSS (why I like CSS Frameworks)

Earlier, I mentioned about TailwindCSS. Like most other CSS technologies, this is a framework. Unlike most other frameworks, this is utility first. What does this means? It means that TailwindCSS provides atomic html classes: classes that each serve one purpose only. So in Tailwind, there is a class called underline that simply sets an element with text-decoration: underline;. There are also other classes, like w-4, which means width: 1rem;. Some classes are short, which may pose a problem when you are using the framework for the first time. Nonetheless, when you get used to it, you’ll find that Tailwind is easier compared to other CSS frameworks.

In other frameworks, like Bootstrap and Bulma, there are cookie cutter css classes for each web idiom, like grid systems for Bootstrap and hero images, breadcrumbs, et cetera for Bulma. The problem I find with is that it isn’t flexible. I like being able to experiment with a bunch of things to make my site look good. However, the nature of these frameworks makes that every website who uses the same libraries look the same. That’s no fun!

Thus, Tailwind is right up in my alley. If you inspect the webpage (press Ctrl+Shift+I), you’ll see that there’s a lot of classes going on. The majority of these are from Tailwind, and due to the power of components in Astro, they are essentially reusable. I don’t have to fear changing a single aspect of the design without ruining the design, because changing a part of the design in a components reflects everywhere automatically, making it consistent with one another.

There are some limitations TailwindCSS has. If you programmatically generate the classes, it will not work. For example, in the code I’ve written for the Admonition component^{† †} We’ll get to that later. , everything feels a little bit janky.

const { type = "normal", title } = Astro.props;
const gray = "border-gray-300 bg-gray-100";
const red = "border-red-300 bg-red-100";
const yellow = "border-yellow-300 bg-yellow-100";
const emerald = "border-emerald-300 bg-emerald-100";
const blue = "border-blue-300 bg-blue-100";

let colorClass;
let headingColorClass;

switch (type) {
  case "error":
    colorClass = red;
    headingColorClass = "text-red-900";
    break;
  case "warning":
    colorClass  = yellow;
    headingColorClass = "text-yellow-900";
    break;
  case "success":
    colorClass  = emerald;
    headingColorClass = "text-emerald-900";
    break;
  case "info":
    colorClass  = blue;
    headingColorClass = "text-blue-900";
    break;
  case "normal":
  default:
    colorClass = gray;
    break;
}

Why bother doing that, when I can do something like this?

const { color = "gray", title } = Astro.props;

const colorClass = `border-${color}-300 bg-${color}-100`;
const headingColorClass = `text-${color}-900`;

That’s considerably shorter, isn’t it?

Well, it does not work at all.

This is actually a problem described by TailwindCSS here. Since class detection is simply just regex, string interpolation absolutely does not work. I guess it makes sense, considering simplicity is king, but it’s simply not making things shorter. I like shorter code because it means that lesser data is transmitted to the web. However, I realized that these code aren’t actually served on the web, since essentially the code above is just part of a build script. Nobody needs to see that; Astro will simply just handle it.

With that said, I something wish I could go back to something like Bulma, because cookie cutters have their place in the chef’s arsenal. However, I would rather have TailwindCSS due to the flexibility it provides, and I understand what things I have to pay for to get what I want.

Thinking about using Headless CMS (and other things in JAMStack)

Another feature of JAMstack website is the concept of APIs. These are similar to traditional website’s backend or servers. They process user input and spits out data and cause the webpage to update.

I honestly do not know how to explain CMS or Content Management System, so I’ll just redirect you to a different website. In this blog. I am referring specifically to headless CMS.

I like the idea of a headless CMS, with a separate thing for my content, so it would not have to meddle with my presentation of website. However, since I am the only one who’ll write on the blog, then I couldn’t really reap the benefits of headless CMSs. I find the use case for CMS should be when you have multiple authors writing for a single website, so this really apply to me at all.

Also, these things cost money. I would like to spend the least amount of cash, since I don’t have any reliable sources of income. Maybe if you tipped me on my ko-fi hehehe.

For websites that distribute static sites, I chose Netlify, because um, I think the pricing is perfect for me? I looked at Vercel and Surge, and they both are less attractive than Netlify in the free tier.

Things I wish Astro implemented right now

As much I would like to evangelize for Astro, I have to admit that this SSG is in its infancy. But before I add my own actual criticisms, I need to preface some things first about Astro.

A lot of things I feel Astro is lacking is the amount of documentation for its API. The function getStaticPaths is particularly confusing, since the example given is not what is actually used in practice. Nobody is making dynamic routes when the routes are predetermined. My opinion is that maybe there should be an example where you would like to display articles having a specific tag in them. So for example, going to /tags/productivity will show you all articles with the tag #productivity.

This isn’t really useful to me:

export async function getStaticPaths() {
  return [
    { params: { id: '1' } },
    { params: { id: '2' } }
  ];
}
const {id} = Astro.request.params;

This is somewhat useful to me, but it’s not clear when you aren’t using a CMS:

export async function getStaticPaths() {
  const data = await fetch('...').then(response => response.json());
  return data.map((post) => {
    return {
      params: { id: post.id },
      props: { post } };
  });
}
const {id} = Astro.request.params;
const {post} = Astro.props;

I also missed Zola’s nth variable or the invocation count, where it tracks the number of times a shortcode is used in a single page.

I also remembered that there is an option for Zola to insert anchor links for each headings. I’m not sure how would I implement that in Astro, other that manually collect all headings and insert the anchor links one by one using Javascript.

I would like to havve at least an Astro plugin for implementing RSS Feeds.

Also, even though Astro recently implemented components in Markdown, it isn’t working correctly. If a paragraph contains a component (like a MarginNote), then that paragraph will not be wrapped in a p tag. I had to make a Pgap component that will simply add a gap between the paragraphs so that it does not look broken.

This is literally the contents of Pgap.astro component.

<div class="mb-4"></div>

There are no resources for web design idioms

During my study of Astro, I found out about hero images. Didn’t know that that’s what they’re called. A lot of jargon are not actually explained by MDN Docs. Most of them are explained by clickbaity articles because people really like to increase their SEO or whatever.

As thus, reading anything about web design is incredibly annoying for me. Why can’t anyone be normal about this.

Unfortunately, everything in regards to blogging is reserved for nondevelopers, because people do not want to customize their own site; they just want somewhere to place their posts. And that’s okay!

My pet peeve is that since everything is targeted towards nondevelopers, the articles that are more useful to me is underneath the vast majority of results in search engines.

I think that there should be an awesome list of web design that describes the different trends in web development, and what are the creative things you can do in creating a blog, an e-commerce site, a social media site, and etc.

A lot of seasoned web developers would probably point you to a resource of design general, and not specific to web design, since it’s really important to know the fundamentals first. However, I already know the basics!

Most blogs are not gimmicky

I love to be creative with my works^{† †} Except for visual art related stuff lol. . However, a lot of blogs don’t usually take an effort to make their content special even through minute details. The main parts of the blog are the header/navigation bar, the body, and the footer. That’s it.

I really liked Eevee’s admonitions and Amos’s dialogue boxes^{† †} Scroll down to see the cute dialogues! . They inspired me to implement something like that for my blog, and I really love the idea of a book-like feel for the website.

If you have any resources for book idioms, please send it my way on Twitter!

Typography is nice (Or why poetry is written on paper, not on the web)

I really like typography. I tried making fonts, but failed because I suck at drawing. I like manipulating the medium of text to convey meaning that cannot be conveyed through conventional means.

My basis for implementing good typography is from this online book. The book discusses the different considerations in improving the typography of anything that has text in it. As a student who likes to have their works pleasing to the eye, this resource is a godsend. There are some things I disagree with, like the author of the book said that ligatures in programming are a no-no.

This contributes to the appeal of writing poetry on the web. I haven’t seen any text-based art using web technologies. As such, I would like to experiment with different kinds of techniques so that I could try making my own story with unconventional means.

Hence, the following section showcase the various components I’ve implemented for this blog.

Admonitions

Admonition, according to Dictionary.com², means “counsel, advice, or caution.” It redirects your attention from the main content, while signifying that this part is considered as side content. Here are examples of admonition boxes implemented in this blog.

// You can add code here!
pub enum JsonValue {
  Null,
  Short(Short),
  String(String),
  Number(Number),
  Boolean(bool),
  Object(Object),
  Array(Vec<JsonValue>),
}

Dialogue Boxes

I also designed simple dialogue boxes similar to Amos’s implementation in fasterthanli.me.

Marginal and Side Notes

Margin notes and side notes are sprinkled along this blog post itself. You can see it along the side of the main content, or in mobile, in between the text in smaller form.

Here, I’ll demonstrate the usage of margin and side notes in a dummy paragraph.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris elementum tortor vel lobortis ultrices. Nunc lobortis mauris purus, et malesuada odio tempor at. Nullam eget porta sapien, non mattis nisl. This is a side note. There is no label here. Curabitur leo erat, sollicitudin ut sapien nec, auctor congue orci. Donec pellentesque sodales felis, ut congue nibh tincidunt ut. Integer tincidunt fermentum laoreet. Donec dignissim, tortor consectetur pretium imperdiet, nunc lectus tincidunt sapien, id feugiat nunc leo volutpat metus.^{† †} This is a margin note. It has † as a marking in the paragraph text. Nam consectetur vitae risus a pharetra. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Mauris ullamcorper metus sagittis rutrum dignissim. Aliquam sem lacus, elementum sit amet justo a, suscipit lacinia mauris. Donec hendrerit nunc tellus, quis dignissim nisi imperdiet vitae. Donec pellentesque metus ac elementum scelerisque. Sed non gravida sem, et vulputate neque.

Footnotes

Footnotes are not actually written by me. It’s a remark³ plugin called remark-gfm⁴, which implements Github-flavored Markdown.

I don’t really know what to use footnotes for, other than putting sources on my claims.

Future Implementations

There are a lot of things I want to make for my blog, but for now, they’ll be placed on the shelf of ideas.

Here are the features I want to implement:

• Fake Social Media Cards (Intended for storytelling, imagine AUs on Twitter)
• Interactive CYOA (Like in r/makeyourchoice, probably utilizes cookies, no database whatever)
• Comments support (Probably not Disqus. I am thinking I should just make a subreddit instead.)
• Analytics using GoatCounter (Sorry, I really like data. It is privacy-aware though.)
• RSS/Atom feeds (I’ll have to reread the documentation again)
• Accessibility (Can someone point me to a direction in making the web accesible?)
• Marginal Table of Contents