It has been a while since I have updated this site. A big reason for this is that I built a new computer and did not have the required Hugo files to continue updating the site. I only ever pushed the public folder to github and not the actual Hugo site development files. At some point, I copied over the minimum required files (the posts, css, etc.) so that I could one day rebuild everything. That day is today! A lot has changed since I last used Hugo but it is just as confusing as I remember (now with even more added confusion? what are/when to use modules?). In any case, we are going to rebuild the site from the ground up and copy over files as necessary to maintain the same look of the original version.

I started this post to document the setup of the website but along the way I ran into a number of issues which made the refresh a pain. Some of the pain points include:

• Content pages are now created with frontmatter in toml instead of yaml.
• Trying to build a "hello world" of sorts with no added themes just fails due to missing files.
• Installing a theme is inconsistent: documentation says to use git submodules but many themes are now using Hugo modules.
• After finding a theme I liked, I had to go through multiple hoops such as upgrading to a newer extended version of Hugo, update some write permissions to .cache, having to install and updated version of npm and nodejs, and npm installing a ton of packages (see image below).
• Even then, I couldn't get the theme to work properly as the json resume feature was failing for some reason.
• In order to get math equations to render the theme comes with some basic instructions to setup katex. Unfortunately, katex is missing features such as equation labels which I tend to use a lot. It also did not properly display inline equations and was rendering them twice.

I always seem to have difficulties when working with Hugo. I tried reading through the documentation but it is so scattered that I end up having 3-4 tabs per topic I am trying to understand. I ended up deciding to switch to a different static site generator, preferably one that was simpler and not node/js based. After reading a few blog posts, I noticed other people have had the same difficulty working with Hugo [1, 2, 3] and switched to Zola. Zola is supposed to be much simpler to use and my experience was just that.

Setting up Zola

The documentation has a nice quickstart tutorial that shows up to get up and running and build some templates. After following the initial set up steps

$ zola init <mywebsite>
Welcome to Zola!
Please answer a few questions to get started quickly.
Any choices made can be changed by modifying the `config.toml` file later.
> What is the URL of your site? (https://example.com): https://example.com
> Do you want to enable Sass compilation? [Y/n]: Y
> Do you want to enable syntax highlighting? [y/N]: y
> Do you want to build a search index of the content? [y/N]: y

the resulting directory structure is

.
├── config.toml
├── content
├── public
│   ├── elasticlunr.min.js
│   └── search_index.en.js
├── sass
├── static
├── templates
└── themes

I tried to immediately view the site with

$ zola serve

and visiting localhost:1111; and to my surprise it just worked! I saw a "Welcome to Zola!" page with a message indicating there was no template to render so it was showing a default page and some recommendations for how to proceed. Already off to a much better start than with Hugo.

I continued following the basic getting started tutorial to get a feel for how Zola works. Overall, it seems intuitive and straight-forward. I like how all of the configuration options are listed on a single page. The same is true for other settings such as the frontmatter options of a page.

Customization

With the basics out of the way, I went straight into downloading a theme for the site. The recommended way is to just do a git clone in the themes folder but I opted to add the theme as a submodule similar to what I did before when using Hugo. This is because my site directory is a git repository itself.

git submodule add https://github.com/justint/papaya.git themes/papaya

In order to get mathjax rendering I simply added the fields in config.toml

[extra]
mathjax = true

[extra.cdn]
mathjax = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"

and then placed the code below into my copy of templates/base.html

{% if config.extra.mathjax %}
    <script>
        window.MathJax = {
        tex: {
        inlineMath: [['$', '$'], ['\\(', '\\)']],
                    tags: 'ams'
             }
        };
    </script>
    <script id="MathJax-script" async src={{/* config.extra.cdn.mathjax */}} ></script>
{% endif %}

This makes it so that I can enable/disable including the mathjax js file by switching a flag in config.toml. Since the include happens in the base.html file it means that all site pages will have the import. It will probably be better to move this flag into the page frontmatter so that we don't import it when it's not used but this also lets us use latex everywhere which is nice. The order of the scripts seems to be important as I was having difficulty rendering inline math on chrome with the reversed order.

Overall the setup was simple but I did run into some issues. Two things I struggled with were: getting the site to compile due a missing banner.jpg file and getting syntax highlighting to use the colorschemes I wanted. For the image issue, the image was in the theme's static folder themes/<themename>/static so I thought it would be found by Zola. I spent a lot of time trying to figure out why it couldn't find it and I'm still not 100% sure, but I believe it is because the image was being modified through a shortcode and so it needs to be at the point of origin. For the colorscheme issue, I am unable to change the colorscheme using a css file and the visitor's light/dark mode preferences. It always defaults to material-light/material-dark even though I set it as gruvbox-light/gruvbox-dark. Other than those issues, everything else was smooth sailing and a lot of my confusion was cleared up by reading the documentation.

The templating engine used, Tera is simple enough that I was able to edit the theme defaults and include some additional features. One example is writing my own shortcode for adding a background color to a transparent image and allowing for the option to resize it. By creating a file templates/shortcodes/imgbg.html with the code

{% if path is starting_with("./") %}
    {% set relative_path = page.relative_path | split(pat="/") | slice(end=-1) | join(sep="/") %}
    {% set img_path = path | trim_start_matches(pat="./") %}
    {% set img_path = relative_path ~ "/" ~ img_path %}
{% else %}
    {% set img_path = path %}
{% endif %}

{% if resize == true %}
    {% set image = resize_image(path=img_path, width=width, height=height, op=op) %}
    <img src="{{ image.url }}" style="background-color:{{bgcolor}};"/>
{% else %}
    
    <img src="{{ get_url(path=img_path) }}" style="background-color:{{bgcolor}};"/>
{% endif %}

I can easily call it from my markdown document with

{{ imgbg(path="./img.png", resize=false, bgcolor="white") }}

There is still a lot left to do but for now I am happy with the result.