After a detour of creating a portfolio site for my CSCE190 class, and now I have free time over the break, it is a great time to rebuild this site from scratch as my last attempts making a mostly accessible site with dark mode didn’t go well. Not the fact that the theme I was modifying, Lanyon, has a sidebar that is not very accessible without JavaScript. Nor modifications to the theme are simple. So keeping in mind of the “Keep it simple, silly” principle, having a minimal design, and no JavaScript on the client, let’s see how I can make a better site than the last one.

Choosing a Site Generator

For getting a simple site up quickly, Jekyll is the choice for me as it was the previous generator I used, and it is the default for GitHub Pages albeit its version of Jekyll is outdated. Compared to Hugo, yes I need to install Ruby, plugins for features that are built in to Hugo and has a short build time. However, there are benefits to use Jekyll than Hugo. The Liquid templates that Jekyll uses is easier to use than Go templates, as I don’t have to use postfix operations for tags and Liquid, as I currently learned, can also suppress the emissions of whitespace by adding dashes in the Liquid variables and tags like so:

This tag will emit whitespace before and after the tag
{% if false %}
    This tag will emit whitespace before the tag
{% elsif true -%}
    This tag will emit whitespace after the tag
{%- else %}
    This tag will not emit whitespace before and after the tag
{%- endif -%}

It is a bit tricky to have consistent whitespace for the output, but you can put dashes and use a minifier for hosting. You don’t need it for variables if there is no whitespace between the HTML and the Liquid tags.

Having native support in the site generator is great, however Jekyll’s plugin systems allows me to modify existing plugins as local plugins. There are some features that I don’t want like CSS injection at build time for admonitions. Changing a setting in a plugin that is not using _config.yaml. Using a plugin that is not hosted on RubyGems. See the _plugins folder at https://github.com/wushenrong/wushenrong.github.io for those examples.

But the major benefit to Jekyll is that it provides a default theme that is has a minimal design, Minima. The latest version supports icons for socials and dark mode, making me do much less work. Still the version that Jekyll provides is old, and I need to modify the theme anyway so time to clone the theme right into the site.

Modifications

The biggest modification I need to make is changing the colors, so the site is compliant with Web Content Accessibility Guidelines (WCAG). These set of guidelines lets designers create sites with disabled people in mind. The hardest and what designers might strive for is WCAG on enhanced contrast. It requires body text to at least to have a contrast ratio of 7 to 1 against the background. However, link to body text needs a contrast of at least 3:1, making it difficult to find a balance between background, body and link colors. After considerations and to keep it simple, I use Minima’s original colors and try to follow WCAG on contrast which requires a text against background contrast of at least 4.5:1, still it’s difficult to satisfy.

Additional modifications I made are edits to the header and footer, including replacing the icons with Font Awesome’s. Update the styles to account for breaking changes in Sass. Add JEKTeX\jektex to render math expressions using KaTeX\KaTeX. Kramdown does have math support with KaTeX\KaTeX but its more out of date than JEKTeX\jektex, and it does not support the usual LaTeX\LaTeX syntax for math mode. But I cannot escape them in code blocks yet, so sticking to the double dollar kramdown syntax is recommended and more portable.

$$a^{2} + b^{2} = c^{2}$$
a2+b2=c2a^{2} + b^{2} = c^{2}

I also added GitHub alerts to the site by using a Jekyll plugin as notice boxes and colors from GitHub, which conforms to WCAG on color contrast.

> [!NOTE]
> This is a note.

> [!TIP]
> This is a tip.

Note

This is a note.

Tip

This is a tip.

Lastly along the way I added more Jekyll plugins, configurations for linters, formatters, minifiers, pre-commit, and GitHub Actions to build and host the site. And it’s much cleaner and nicer than before. Any modifications and source code of this site can be seen at https://github.com/wushenrong/wushenrong.github.io.