Web on Giovanni Bassi

Modernizing the website using Bootstrap 5

giggio@giggio.net (Giovanni Bassi) — Wed, 02 Apr 2025 13:00:00 -0300

In the last few days, I updated this site to Bootstrap 5. I took the opportunity to make several improvements and I want to share how that process went.

More than just an update, I used this chance to enhance various parts of the site, including where it touches Hugo.

Bootstrap 5

Migrating to Bootstrap 5 turned out to be much smoother than I expected. I thought it would be an extremely laborious process, but in practice, it was pretty straightforward. There are countless articles and even the official documentation that explain every step, so I won’t dive too deep into the technical details of the update itself. During the process, I realized I could improve other parts of the site, so I decided to work on them as well.

If you want to check out the update, the commit is on Github.

EcmaScript modules

Bootstrap 5, released in mid-2021 (three and a half years after version 4.0), brought full support for ES Modules, which are widely supported by 2025. Previously, my code loaded scripts and styles via CDN. That took advantage of users’ caches but ended up downloading the entire library, including unnecessary code and styles since not everything was used. Plus, it didn’t use ESM.

With ESM, I was able to apply tree shaking – the removal of unused code. Luckily, Hugo already offers an option to perform this process, making everything extremely simple.

I created a file called vendor.mjs to list only the dependencies I actually use. This is the file that gets compiled. It basically exports the libraries, like this:

export { Popover, Tooltip } from 'bootstrap';

Using Hugo’s js.Build method, the bundle is generated automatically. In short, it looks like this:

{{ with resources.Get "/js/vendor.mjs" }}
 {{ $opts := dict
 "minify" hugo.IsProduction
 "sourceMap" "linked"
 "format" "esm"
 }}
 {{
 printf `<!-- Vendor file: %q -->`
 (js.Build $opts | fingerprint "sha256").RelPermalink | safeHTML
 }}
{{ end }}

This file is then imported into my main script, the script.js, with a simple import. It starts off like this:

import { Popover, Tooltip } from './vendor.mjs';

I simply import this file, without building it, which means the vendor file isn’t inlined. The challenge was that the file name changes (because of the fingerprint), but I solved that with an importmap script.

I started using Bootstrap installed via Npm, which made the process a lot easier because Hugo’s js.Build uses esbuild to automatically search within the node_modules directory.

Another advantage is that the vendor file remains static, which allows browsers to leverage their cache extensively. It only changes when I update the dependencies. When that happens, the compiled file name changes, solving browser cache issues. The same goes for script.mjs, though that one tends to change more often as new features are added.

Fun fact: rewriting this script was the only part that Github Copilot managed to automate during this migration – and it generated a bug that I fixed right away.

Sass compilation

I had already been performing tree shaking and analyzing all of my Sass/CSS, but the Bootstrap CSS was loaded entirely via CDN. Since Bootstrap’s Sass is already available in node_modules, I started integrating it directly, eliminating all of the unused Bootstrap CSS. I lost the potential cache benefits from the CDN, but I believe the vendor file will make up for that.

The challenge was tweaking my unused CSS analysis function, as much of the CSS remaining in the final file (before tree shaking) wasn’t written by me. This script cross-references the generated HTML with the CSS and points out unused selectors, allowing me to remove them manually afterward. With a bit of Bash and open-source tools, I managed to sort it out. If you’re interested, check out the unused-css script in the package.json.

Goodbye jQuery

I’m incredibly grateful to jQuery – it paid many of my bills and was a great companion – but by 2025, it just doesn’t make sense anymore. While Bootstrap 4 depended on jQuery, Bootstrap 5 does not. So, I removed it.

The problem was that the lightbox library I had chosen depended on jQuery, and I didn’t want to keep it around just for that reason. I decided to replace it with Photoswipe, which already supports ESM, making implementation easier. To import it, I used another script with importmap, pointing directly to the CDN. And with that, I also eliminated the extra files from the previous library, which required me to also deliver its images. Now, everything comes from the CDN.

Switching FontAwesome to JS + SVG

After optimizing Bootstrap’s JavaScript and CSS, I decided to tackle other areas of the site. I noticed that the web font files for FontAwesome were quite large – with three groups of free fonts (solid, regular, and brands), totaling over 300KB. On the other hand, FontAwesome offers an option to use JavaScript + SVG instead of fonts, without changing the HTML. This approach even allows for tree shaking, as described in the documentation.

The biggest challenge was the documentation, which ended up being confusing, especially with the constant promotion of premium icons. I’m considering switching to Bootstrap’s own icons or at least mixing some of them in, but I’m still evaluating. Either way, figuring out how to use FontAwesome’s JavaScript APIs wasn’t simple since there isn’t a complete example available.

I used the same technique with the vendor.mjs file, including only the icons I need. Creating this file correctly was challenging, but with some Bash-fu, I managed to generate a file whose sole purpose is to import the icons I’m using – the fontawesome.generated.mjs. If you want to see how it was done, all of the project’s Bash code is concentrated in one file (and I promise I’ll write a detailed post about it soon): find it here.

The generated file, in simplified form, looks like this:

import { dom, library } from '@fortawesome/fontawesome-svg-core';
import { faMastodon } from "@fortawesome/free-brands-svg-icons";
import { faCheck } from "@fortawesome/free-solid-svg-icons";
library.add(faMastodon, faCheck);
export { dom, library };

In the actual file, lines 2 and 3 contain all the icons.

Using it is super simple: I created another file called fontawesome.mjs, which imports the generated file and contains a single function responsible for initializing the icons:

import { dom } from './fontawesome.generated.mjs';
export function initFontawesome(...nodes) {
 if (nodes.length === 0)
 // essa chamada inicializa os ícones da página inteira:
 dom.i2svg();
 else
 for (const node of nodes)
 // essa chamada inicializa apenas os ícones dos
 // elementos recebidos e é usada quando um elemento
 // com ícone é adicionado dinamicamente à página:
 dom.i2svg({ node });
}

Finally, this file is imported and exported in vendor.mjs.

You might have noticed that the initFontawesome function optionally accepts a list of nodes. To avoid having to call it manually everywhere, I created a MutationObserver that triggers it whenever an <i> element is added to the DOM. So when that happens, the <i> is removed by FontAwesome’s code and replaced with an <svg>.

Dark Mode

One of the reasons for updating to Bootstrap was its new implementation of light and dark themes, something essential for me as a dark mode fan. My site’s all-white look was really bugging me, so this change was a top priority!

Moving Sass variables to CSS

The documentation for Bootstrap explains the process well, and the implementation was very straightforward. The challenge was that my code, inherited from a theme, made heavy use of Sass variables. For an effective dark mode implementation, I needed to migrate to CSS variables (or, more accurately, CSS custom properties). I carried out this migration in this commit – and it was super easy.

Implementing dark mode

The implementation was super straightforward. Preferably, Bootstrap doesn’t rely solely on the prefers-color-scheme media query, since that would make it hard for users to switch themes without altering their browser or OS settings. Instead, it uses the data-bs-theme-value attribute, which you can place anywhere (typically on the <html>).

With that done, you just need to create a section for default CSS variables (which in my case became the light theme), and another for the alternative (dark) theme, something like this:

:root {
 --body-color: white;
 --text-color: black;
}
@include bootstrap.color-mode(dark) {
 --body-color: black;
 --text-color: white;
}

The importance of migrating to CSS variables beforehand becomes clear here.

The Sass color-mode mixin basically inserts the content inside the mentioned attribute, like so:

@mixin color-mode($mode) {
 [data-bs-theme="#{$mode}"] {
 @content;
 }
}

And the above code compiles to:

:root {
 --body-color: white;
 --text-color: black;
}
[data-bs-theme="dark"] {
 --body-color: black;
 --text-color: white;
}

Since the [data-bs-theme] attribute is defined on the <html>, it has higher specificity than :root, altering the CSS variables and consequently, all the site’s colors.

Bootstrap’s documentation provides a base code for this functionality, which I used and tweaked slightly. It only uses the media query until the user opts to switch themes, ensuring a very flexible system.

The biggest challenge wasn’t implementing dark mode, but finding a color scheme that I liked while still respecting the visual identity of the light theme, especially for blog post readability. For that, the predominant background needed to be black – for me, dark mode is truly black. On OLED screens, every turned-off pixel counts! No dark gray. In the end, I liked the result, but I still need to live with it a bit longer to see if it really works for me.

So, did you like dark mode? Any suggestions for improvement? Leave your comment down below!

Adapting generated themes from tools

Two widgets didn’t automatically adapt: the Giscus comments and Hugo’s syntax highlighting. Both used fixed themes, but luckily they offer customization options with just a few lines of JavaScript. Giscus provides an API to adjust the theme, while Hugo’s syntax highlighting allows using external CSS – you just need to change the href of the <link> that loads the highlight CSS.

I’m even thinking about offering users the option to change just the syntax highlighting theme, with a subtle screen element that allows for this change. It’s the kind of customization that’s only possible when you have complete control over the HTML, something that would be quite labor-intensive in WordPress.

Conclusion

This journey took me about 30 hours, with a good portion of that time dedicated to research. If I had to do it again, it would definitely be faster now that I’ve learned the parts of the work I didn’t know before. It was an extremely enjoyable experience getting back into frontend development after a few years, without relying on SPA libraries/frameworks or even TypeScript. Seeing how modern and accessible CSS and JavaScript have become was refreshing. Perhaps soon, Sass won’t even be necessary. JavaScript handles a codebase of this size very well, especially with the TypeScript compiler constantly checking the code, which ends up being a huge help.

I still have other stories from this update to tell, but since they aren’t directly related to adopting Bootstrap 5, I’ll save them for another post.

So, did you know you could do all this with a static site generator? Were you aware of these new JavaScript and CSS innovations? Drop a comment below and let me know what you think!

It’s so much fun working with Hugo, Bootstrap, modern JavaScript, and CSS!

Under the hood: creating a site with Hugo

giggio@giggio.net (Giovanni Bassi) — Mon, 24 Mar 2025 15:00:00 -0300

Evaluating the Options

When I decided to create a new website, the first option that came to mind was WordPress. I’ve been using it for many years and I like it. Since I’m also well-versed in infrastructure, setting up a service in the cloud and running it is very simple. It’s tempting.

But there are performance challenges. While I maintained the Lambda3 site, we faced several problems. Initially, we solved them with cache plugins, but over time, even that wasn’t enough, and we started using Cloudflare’s cache, which in fact solved the problem definitively.

It was a bit much: PHP + MariaDB + Cloudflare, all just to serve a static site. And it still needed plugins to write in Markdown, which was what I wanted from the start. Wasn’t there a better solution?

My main argument in favor of WordPress is its ecosystem of plugins, which is unbeatable. But for a static site, that seemed excessive. I just wanted a site with a blog and a few sections. Did I really need all of that?

Giving up WordPress meant having to deliver everything it and its plugins do. My minimum requirements included static pages, a blog, and RSS. Along the way, other needs emerged: posts categorization and tagging, blocking generative AI robots, image optimization, among others. Not to mention the common frontend needs, like compiling styles written in Sass.

Choosing Hugo

Decided to use a static site generator, I went to evaluate options. I wanted fast software, under constant development, mature and free. It needed to meet my needs and offer flexibility for the future. Hugo won, but other good options were Astro, Jekyll, and Zola. I evaluated others, but these were the ones I considered the most. It’s been a while since I made the decision for Hugo; I started the project months ago, and it was shelved for a while.

Hugo met everything I needed. With almost 80 thousand stars on GitHub, it is a tool in constant update, with almost 9 thousand commits. Made in Golang, it has good documentation and an active forum for questions.

Moreover, it features hundreds of themes distributed across the internet. Since I’m not a designer, that was essential. I chose the Roxo theme, which I ended up completely customizing. The only thing that will still give me trouble is updating Bootstrap 4 to version 5, something that isn’t so trivial.

What’s Good About Hugo

Development Experience

The development experience with Hugo is excellent. The built-in server, started with hugo server, runs the site and hot reloads whenever a file is changed. Changes in CSS don’t even reload the page; they are applied dynamically. On my machine, a Markdown post takes 22ms to process, and the entire site half a second. On GitHub Actions, the build takes 2.5s, so YMMV. Template development is equally fast; you save and immediately see the result, without delay. The experience is the same as developing a dynamic site with server-side rendering, and with immediate feedback, somewhat better than working on an Angular or React SPA.

Flexibility

With Hugo, you have full control over HTML, CSS, and JavaScript. You don’t depend on whoever wrote a plugin to adapt it to get to the result you want. There are plugins for Hugo (called modules), but the most common is to find code snippets to customize as needed. Since it is very extensible, that’s enough. I really liked this approach, which allows for enormous freedom.

Template System

Hugo uses HTML templates to structure the site and Markdown for content. This is useful because metadata remains in the front matter, facilitating translations, RSS, and other features.

Its template system is powerful. The templates are divided into types, such as sections (lists of pages) and individual pages. There is support for partials, allowing for the componentization of reusable elements like header and footer.

The templates can generate any format, such as JSON, XML, or others. This is essential for features like sitemap.xml and RSS.

Data Features

At the footer there is a section of podcasts I listen to and blogs I read. Both were built using a Hugo feature to reference data sources. You can create CSV, JSON, TOML, YAML, and XML files (I used YAML) and use them as a source.

For example, creating a YAML data file for podcasts, like this:

- name: Medo e delírio em Brasília
 url: https://medoedelirioembrasilia.com.br/
- name: Hipsters.tech
 url: https://www.hipsters.tech/

And then using it, like this:

{{ with hugo.Data.podcasts }}
 <li><a href="{{ .url }}">{{ .name }}</a></li>
{{ end }}

Shortcodes and Code Fences

There are also shortcodes, which are ways to easily create HTML, like embedding a YouTube video, or creating code with syntax highlighting.

{{< youtube EFAe8W3n2ks >}}

The codes above were generated solely with code fences — those codes with three or four backticks in the markdown — and they use a shortcode under the hood. This is an example of code fences with yaml:

```yaml
prop: true
```

Taxonomy

Hugo has a taxonomy system, which is a way to categorize your pages. The most common, and what I’m using, are categories and tags for blog posts, but you could use it to organize anything. I also used it to build pages for types of contributions (for example, videos – check its code on Github).

The example they use in the documentation is with movies and actors. Thus, a movie page can list its actors. Actor is the taxonomy, the actor’s name becomes the term. The cool thing is that you can create pages for these classifications, both for the taxonomy and for the term. That’s how I have here the categories page, tags, and each of their terms, such as the tag blog. The pages, the taxonomies, and the terms are data that you can manipulate.

Build

During the build, all pages are generated, the entire site. With the dev server running you can choose whether to rebuild everything or just the page that changed. It builds the lists of pages, the taxonomies, everything. It also caches everything it did, such as image manipulations and files it may have downloaded.

Hugo supports environments. In dev, it doesn’t optimize anything (and this is configurable). The prod build, on the other hand, can do a series of things. Just look at what happens on my site:

Sass compilation, concatenation of all CSS, tree shaking (with PostCSS), minification, and fingerprinting.
Optimization of all images, which are converted to webp and in some cases resized.
HTML minification

I also perform critical CSS analysis with the critical tool, which is run for each individual page. I also generate search with pagefind (you can try it at /search – and I admit I spent little time on it, but it’s working).

This happens locally, if I want to test, and also using the workflow from GitHub Actions, which also performs linting and spell checking (with cspell).

Other Features

Hugo supports multiple languages, and I’m using that on this site (click the little flag at the top in the header).
The index, at the beginning of this post, was also built using a page metadata, the .TableOfContents (check out the source code).
You can use external resources that can be downloaded, such as an image, or a CSS file, or JSON, and then process them and generate content from them. That’s how I’m generating my robots.txt file (see the source on Github), like this:
```
{{- with try (resources.GetRemote "https://link/para/robots.json") -}}
```
(notice the try?)
The integration with Node.js resources is excellent, thanks to the ability to mount directories and files. You can specify that any directory should be available for the site, and when accessing the resource, it copies the necessary files. That’s how I’m doing it with the files from Font Awesome, check out how the configuration file looks:
```
module:
 mounts:
 - source: node_modules/@fortawesome/fontawesome-free
 target: assets/css/fontawesome
```

What Could Improve

Hugo’s main problem is the lack of debugging. When you’re deep into template developing and something doesn’t work as you’d like, ideally you would be able to debug the problem while the site is being generated, but the tool does not offer that.

We’re stuck with good and old writing to HTML approach, using the debug.Dump instruction, when the result appears directly in the HTML, or the warnidf function, which generates a log in the terminal. It helps, but it’s an experience that could be improved. I struggled a bit until I discovered that these existed, so here’s a tip for those who are starting.

Conclusion

I still have more to say about Hugo, but this post is already long. The main point is that Hugo is an excellent tool for static sites. It perfectly solved my problem, it’s a pleasure to use, and from what I see, it will continue to serve me for a long time.

I still have more to talk about regarding the entire structure around it, such as how I used GitHub Pages, the use of Nix to structure the tools, and much more, and that will also be saved for future posts.

What do you think of Hugo? Comment below!