Browsing through the historical commit records, the site has undergone numerous theme switches. Each theme switch involved some custom modifications, and this is where I’m documenting the approach to customizing themes. My Github repository briefly maintained the even theme, but due to my obsessive-compulsive tendencies, I resisted upgrading the hugo compiler to the latest version, which resulted in incompatibility with the even theme, so I switched back to the stack theme.

Hugo’s Modularity

When we talk about modularity, many people think of Nginx modules and IDEA plugins, among others. Typically, I can upload some modules to satisfy my differentiated needs. The reason everyone likes this kind of module is that it’s sufficiently flexible – you don’t have to put in too much effort to meet your own requirements. Because often, even though the overall situation is similar, there are always some details that differ. This also illustrates the complexity of software, not just technically but also from a business perspective. Most of the time, we face business complexity. This is precisely where the saying “it’s like crossing a mountain range” best applies. Today, not only the internet industry and finance, but even traditional manufacturing industries are using information systems to help businesses with their production and management. Even a leave system can have differences between companies in the same industry.

Unlike the modules you might be familiar with, Hugo’s modules are different – they don’t focus on meeting differentiated needs based on functionality. Instead, they rely primarily on directory structure to identify identical structures.

Resource link: 07. Hugo Architecture — Hugo Modules

[[imports]]
path = "github.com/CaiJimmy/hugo-theme-stack/v3"

The git submodule approach can still be used, and this article doesn’t recommend it. If you introduce a theme, maintaining it will be more complicated – you’ll need to manage the theme as a separate Git repository.

Theme Modification Logic

Once you have a solid understanding of the foundational concepts of modularization, customizing themes becomes much simpler. Hugo themes are currently assembled from multiple different modules. To modify one module, simply locate its corresponding template file and make the changes directly.

As extracted from the official stack documentation:

Using this method, there will be no files under the themes directory. To modify a theme, you must copy the file you want to modify into the same directory under the layouts directory.

For example, to modify the themes/hugo-theme-stack/layouts/partials/head/custom.html file, you must copy it to layouts/partials/head/custom.html and modify it there (copying the code from the theme’s repository). The same applies to the assets and static directories.

How to Find Template Files

Conventional Approach

Review the source files of the topic, understand its design rationale, identify the corresponding template file, and modify it.

Brute Force Approach

As I’m not very familiar with frontend code, I sometimes resort to a brute force approach, such as opening the corresponding page directly in the browser, finding the areas I want to modify, and using “Inspect Element” to pinpoint the css name, then searching the source code for the relevant file, copying it into the site directory, and making changes.

Tips

The official setup provides a default file for customizing styles. To modify specific areas, we can split them into multiple files and import them using custom.scss. This approach allows for better management of style files.

Consolidated Modifications (6h)

It’s now the first year of AI coding, and detailed content will not be pasted here for brevity; instead, we’ll simply list some of the modifications made to this site, such as adjusting the copy button styles, reconfiguring the code block styles, and ChatGPT was easily handled.

• Overall: Global text style, retaining the display style previously used by merging even with info cn, which is friendly for Chinese
• Homepage: Added mouse interaction animation to the right navigation
• Homepage: New article summaries added (took quite a while to implement using a clever workaround)
• Scroll Bar: Improved the styling of the scroll bar
• Code Blocks: Introduced the highlight.js code highlighting plugin, beautifying the code block styles
• Article Details: Some content is from reprints, with new author information display and original link display
• Archive Pages: Removed the color mask from the category images at the top to display the original image
• Archive Pages: Added a statistical display panel for categorization by year
• Archive Pages: Two-column layout

The stack theme has a high component reuse rate, which also led to the lengthy time taken to add new article summaries to the homepage. After modifying the corresponding components, changes occurred in the article details page as well, resulting in redundant display of content. The golang template syntax wasn’t very familiar, so it took up quite a bit of time. Component parameter passing was never resolved, and ultimately, through a clever workaround, a JavaScript script was independently introduced to the homepage to implement the summary preview by using custom special variables.

Sometimes, high component reuse can also be a problem, leading to unintended consequences when modifying one place affecting others. Therefore, when modifying themes, you must pay attention not to disrupt existing logic.

Comments

This guy’s modifications are more refined: https://blog.reincarnatey.net/2024/0719-better-waline/ This site simply enabled the Waline comment system, as the stack theme defaults to supporting Waline. Just configure it in the config.toml file.

Recommend contacting via email on the homepage, this site does not open the comments section