migrating to new blog framework zola
- Zola is a static site generator (SSG) library written in Rust, competing in the same field with Hugo, AstroJS, and Jekyll
- It uses Tera as its templating engine to translate variables to static HTML pages
- Zola's build time performance is faster than Hugo, which implies it already beats AstroJS and Jekyll. Build performance is relevant for developers during development. When a website is deployed, its performance are more related to factors such as assets size, Javascript usage, web server loads, etc.
mdbook
I currently own 2 static websites. Both of them are generated with mdbook,
which is another SSG library written in Rust.
However, the purpose of mdbook isn't for building websites, mdbook exists
to serve documentation type contents, the same way as Gitbook does without the
hassel of HTML or CSS. That means mdbook is engineered to be as simple and
clean as possible as long as developers knows how to write in Markdown. For this
reason, mdbook style and layout are fairly restricted. To build a website,
a more flexible library should be considered, so that I can design proper
landing page, blog, HTML buttons, etc.
custom design means byebye to mdbook
While I have used mdbook as a convenient website builder, I felt like it's
time to apply more personal touches onto the websites I own. Unfortunately for
me, I do not have much experience in either HTML and CSS, so reworking on both
of my websites have been a longer journey compared to people who have more
web frontend development knowledge.
The designs I settled on were inspired by RPGUI and Drew DeVault's blog. One is retro and ultra stylish, the other is minimalistic and almost barebone. Since there are 2 websites of my own, I went ahead to use both different design themes for the 2 sites.
roomlab wiki
Roomlab wiki has been with me for a long time, its contents came from my personal collection of scripts and notes on building and deploying services and infrastructure on the internet. For this site, I chose RPGUI as theme.
RPGUI isn't a theme made for Zola, so there isn't anything I can use
out-of-the-box, except its image assets and CSS. But since its CSS is entirely
written with custom classes, these class cannot be directly translated by
Zola's Markdown translation layer pulldown-cmark. Because pulldown-cmark
expect CSS to be written on generic CSS classes themselves instead of custom
defined classes. So before I can use RPGUI, I would need to manually port
its custom classes onto generic CSS classes so that Zola can translate
Markdown directly to HTML with the correct styling.
For instance, a trivial conversion from a custom button class from rpgui.css
to generic css/scss class is as such:
.rpgui-button {
/* hide button default stuff */
background-color: Transparent;
background-repeat: no-repeat;
border: none;
overflow: hidden;
outline: none;
/* etc. */
}
To a generic css class that Zola can use:
button {
/* hide button default stuff */
background-color: Transparent;
background-repeat: no-repeat;
border: none;
overflow: hidden;
outline: none;
/* etc. */
}
Unfortunately, a sizable potion of the "conversion" isn't as straight forward,
it required consideration on a rather artistic side by trail and error. For
example, nav element doesn't exist from rpgui.css, this part of the work
required to be ported with some original thoughts:
nav {
width: 100%;
font-weight: 600;
margin-bottom: 2rem;
padding-bottom: 0.3rem;
justify-content: space-around;
border-bottom: 1px solid var(--secondary-color);
color: var(--secondary-color);
/* etc. */
}
- color pallet needs to be abstracted
- padding, margin needs to be re-adjusted for web contents
- mouse hover behaviour needs to be implemented
Another aspect of porting css file is about security and privacy.
The original CSS file relies on a remote Google font to be downloaded on the client browser, which isn't a bad deal for developer like myself. But for whoever viewing my contents, their IP address will be exposed and tracked by Google from a seemingly innocent download of the font file.
For this reason, I looked everywhere to find a novelty font that fits the artistic style for my website with FOSS friendly license so that I can remove the reliance on Google's font. Then my server simply serves the font file to the browser.
The fonts I settled for is called OldSchoolAdventures.
Overall, the process of porting from custom to generic CSS classes took me some considerable time as I began to learn each CSS property and what they eventually be rendered on screen. A lot of them became less functional after porting, so debugging CSS rules took most of my time. In return, I earned the knowledge and experience about CSS. In addition to new to CSS in general, I was misguided to learn about the syntax and historic context of SASS and SCSS. But at the end, knowing basic CSS and SCSS was sufficient.
After a few days of struggle, my port were done.
My next step is to publish my ported version of RPGUI as a Zola theme and make it available on Zola's themes directory.
hidden css page
During roomlab's rework, I have noticed that having a page that showcases all the CSS styling had helped me discover styling issues early. So I dedicated a CSS template for this purpose. To hide this page from the eyes of non-developers. I have hidden it in such a way that it can only be accessed via explicit URL, otherwise regular users will not be able to navigate to it by using the website's nav bar or links.
So I called this page the "hidden css" page. It's availble to see by visiting
the https://<domain_name>/css.
I soon realized this was in fact a great practice in general. So I applied this idea to all websites I own, even websites that I do not intent to publish.
potato
potato is a another website of mine, it serves as my personal blog. This is where I can freely write down things that are unrelated to building homelab. For this site, I decided to custom build a CSS file that provide a style of academia feel. The original CSS came from Simple CSS. It's heavily modified to fit my personal color preference.
Unlike RPGUI, creating custom CSS based on SimpleCSS was simple, the only thing I changed was its color palette and body real estates. The rest were minor updates.
For example:
:root {
--background-color: #1b2b34;
--primary-color: #ffa500;
--secondary-color: #b5a642;
--tertiary-color: #d4c4b0;
--quaternary-color: #132c76;
--text-color: #f5f5f5;
--link-color: #d30;
}
body {
font-family: Terminess, Ubuntu, sans-serif;
background-color: var(--background-color);
padding: 0 3rem 3rem 3rem;
color: var(--text-color);
margin-right: auto;
margin-left: auto;
line-height: 200%;
font-weight: 400;
max-width: 63rem;
}
Note that I have removed its Javascript files and other unused assets to reduce the size of the website.
result in performance
After migrating 2 websites to Zola framework, its resulting pages were loaded much quicker than before. Because it came without the bulky default CSS options and Javascript local search feature.
To verify a website's load performance, I tested it against Google's Lighthouse Metrics, and both sites have generally achieved 100% on all geographic regions.
To prove the performance of my website against others', here is a side-by-side comparison against Amazon 🙂
critique
Zola isn't for everyone, it's too early to achieve feature parody to Hugo or AstroJS. However, having full feature parody against Hugo or perhaps Gatsby often brings unneeded bloats to Zola's core. Having more diagraming libraries that work with Zola is currently an ongoing effort for the community. And that I believe is a better focus than providing full feature parody in comparison to other SSG libraries.
As soon as there are options for diagram, Zola should have a solid ground to become the fastest and most easy-to-use SSG on the market.