DEV Community: Xiaoliang Wang

Create a Hugo Theme from Scratch - IV

Xiaoliang Wang — Tue, 15 Oct 2024 09:00:00 +0000

This is a series of blog posts documenting my journey of building a Hugo theme from scratch: https://github.com/tomowang/hugo-theme-tailwind. The series consists of four articles, this is the fourth one:

I. Introduction to the background of building the Hugo theme, my ideas for the theme's features, and the development environment setup
II. The main directory structure of the Hugo theme, the technologies involved, and the main framework of the theme I created
III. Additional features of the Hugo theme, including dark mode, responsive design, multilingual support, code highlighting, and build pipeline
IV. This part describes non-code-related content, including continuous integration (CI), how to submit to the official theme site, and SEO-related data

Continuous Integration

With the functionalities mentioned in previous articles completed, most of the coding work is done. However, as a project intended for others to use, there are still some additional tasks to handle.

As a Hugo theme repository, continuous integration can encompass several aspects, such as automated deployment of the example site and automated version releases based on git tags. Regarding the example site, the Hugo-generated static site can be easily published to GitHub Pages, and GitHub Actions provides actions to operate GitHub Pages. Here, I used three actions:

actions/configure-github-pages - Configures GitHub Pages and retrieves some meta information, such as base_url
actions/upload-pages-artifact - Uploads resources to GitHub Pages
actions/deploy-pages - Deploys to GitHub Pages

The GitHub Pages related workflow requires additional permissions:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

Additionally, the Hugo compilation parameter --baseURL needs to use the meta information from GitHub Pages:

- name: Setup Pages
  id: pages
  uses: actions/configure-pages@v3

- name: Build with Hugo
  env:
    # For maximum backward compatibility with Hugo modules
    HUGO_ENVIRONMENT: production
    HUGO_ENV: production
  run: |
    hugo -s exampleSite --minify --gc --themesDir ../.. \
      --baseURL "${{ steps.pages.outputs.base_url }}/"

The GitHub Actions code is placed in the .github/workflows/ directory and is triggered automatically by committing code.

Moreover, I configured DNS resolution pointing the GitHub domain hugo-theme-tailwind.tomo.dev -> tomowang.github.io so that users can access the example site through https://hugo-theme-tailwind.tomo.dev.

Promotion

To reach a wider audience for the theme, the best way is to submit it to the official theme site. Hugo provides a GitHub repository to build the official theme site https://themes.gohugo.io/, and it also details the submission process.

Specify the supported Hugo versions in the config.toml configuration file.
Use the theme.toml file to describe some meta information about the theme, including name, copyright, tags, author, etc.
A descriptive README document, which serves as the main page on GitHub and is used to display the theme details on the site.
Theme screenshots and thumbnails with the following size requirements:
1. Screenshot (screenshot.png or screenshot.jpg), with a minimum size of 1500×1000 pixels
2. Thumbnail (tn.png or tn.jpg), with a minimum size of 900×600 pixels

After completing these steps, follow the git workflow to fork, modify, commit, and submit a PR to the official theme repository. I submitted my PR #391. Fortunately, the PR was quickly merged into the repository, and finally, the theme became accessible on the official theme site: https://themes.gohugo.io/themes/hugo-theme-tailwind/.

Other promotional channels include the official forum, where there is a dedicated section new theme for discussions about new themes. I created a new topic to introduce the theme.

Additionally, some third-party theme sites collect data based on the topics configuration in the GitHub repository, such as builtatlightspeed. By configuring the hugo-theme topic in the GitHub repository, these theme sites can crawl and index the repository. The complete Topics I configured are theme hugo-theme hugo gohugo hugo-blog hugo-blog-theme tailwind tailwindcss tailwind-theme hugo-blog-template.

Currently, the theme is automatically listed on the following sites:

Of course, there are other theme sites where you can submit through PRs, such as https://jamstackthemes.dev/.

Future

After submitting the theme to the community, some users tried it out and provided feedback, suggestions, and questions, which I addressed and handled one by one. Currently, the number of Stars on the GitHub repository is as follows:

Here is some data for reference:

When searching for the keyword "hugo theme tailwind" on Google, the theme page ranks quite high.

From Google Analytics, we can observe that the most traffic comes from the official theme site https://themes.gohugo.io, which is related to the Google search ranking.

This concludes this series of blog posts. Of course, the theme I created is relatively simple. If you are interested, you can try it out and provide valuable suggestions.

Create a Hugo Theme from Scratch - II

Xiaoliang Wang — Tue, 15 Oct 2024 09:00:00 +0000

This is a series of blog posts documenting my process of building a Hugo theme from scratch (https://github.com/tomowang/hugo-theme-tailwind). The series consists of four articles, and this is the second one:

Hugo Theme Basics

Before we start building the theme, we need to have a basic understanding of some terms, syntax, and directory structure of Hugo themes.

Basic Syntax

Hugo uses html/template to render content, and methods and variables are accessed through {{ }}. Commonly used syntax is as follows:

Variable rendering - {{ $address }}
Method call - {{ FUNCTION ARG1 ARG2 .. }}

Loop

{{ range $array }}
    {{ . }} <!-- The . represents an element in $array -->
{{ end }}

Conditional statements - with if else etc.

{{ with .Params.title }}
    <h4>{{ . }}</h4>
{{ end }}

{{ if (isset .Params "description") }}
    {{ index .Params "description" }}
{{ else }}
    {{ .Summary }}
{{ end }}

Pipeline - {{ .Title | .RenderString }}
Context . and global context $.
Use hyphen - to remove extra empty strings
```
<div>
  {{- .Title -}}
</div>
```

For a detailed description of the syntax, you can refer to the official documentation https://gohugo.io/templates/introduction/.

Hugo also provides many built-in variables, which are rendered through the theme file to ultimately generate static pages:

Site - Site object
Pages - Aggregation of pages
Page - Single page object
Menu - Menu list
Menu entry - Single menu object
Taxonomy - Single taxonomy object

When using a theme to render page content, we need to call attributes or methods based on the corresponding variables to finally present the content we want.
For example, if we want to display the reading time of a single article, we can call the ReadingTime method (https://gohugo.io/methods/page/readingtime/) of the Page variable.
Some objects have many methods, you can refer to the official documentation for details https://gohugo.io/quick-reference/methods/.

Directory Structure

After we create a basic Hugo theme, we can use the command tree -L 2 -d . to view the basic structure of the theme directory:

.
├── archetypes
├── assets
│   ├── css
│   └── js
├── data
├── i18n
├── layouts
│   ├── _default
│   └── partials
└── static

The meanings of the relevant directories are as follows:

archetypes - Templates for creating new content pages
assets - Static resource files, usually processed through the resource pipeline
data - Used to store additional data, you can refer to https://gohugo.io/templates/data-templates/
i18n - Stores localization files
layouts - Core template layout files
static - Static files that will be copied directly to the final public directory

The most important one is the layouts directory, which determines the pages supported by the template and the layout of the pages.
Hugo uses a set of rules to query which template file should be used for the content page. A typical site consists of the following types of pages:

Home page
Single page
List page
Term page
Term list page

The lookup order can be referred to in the official documentation https://gohugo.io/templates/lookup-order/.
The official documentation describes the complex lookup order, but most page structures of the theme are similar, so in actual situations, only a few pages need to be defined to achieve the desired result.

Theme Content Construction

tailwindcss

Before starting to build, we need to install tailwindcss. I made some adjustments based on the official documentation:

# install
pnpm install -D tailwindcss
# init
npx tailwindcss init

Install tailwindcss and generate tailwind.config.js configuration file through the above commands.
Since our page content is in the layout directory, we need to adjust the content configuration in tailwind.config.js:

content: ["./layouts/**/*.html"],

Place the tailwindcss reference in assets/css/main.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

Then we can monitor the page content and generate the actual CSS file to be used through the following command:

npx tailwindcss -i assets/css/main.css -o ./static/main.css --watch

Basic Layout

Based on my needs and the description of the Hugo directory structure in the previous section, I finally defined the following basic pages:

baseof.html - Carries the layout of the main page
list.html - List page, term list page
single.html - Single page, the main content page
terms.html - Term page

Through the baseof.html file, we define the basic template, which will be applied to all pages. Its core content is as follows:

<!DOCTYPE html>
<html lang="{{ or site.Language.LanguageCode site.Language.Lang }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
<head>
  {{ block "title" . }}
    <title>
      {{ if .IsHome }}{{ $.Site.Title }}{{ with $.Site.Params.Subtitle }} —
      {{ . }}{{ end }}{{ else }}{{ .Title }} ::
      {{ $.Site.Title }}{{ with $.Site.Params.Subtitle }} — {{ . }}{{ end }}{{ end }}
    </title>
  {{ end }}
  {{ partial "head.html" . }}
</head>
<body class="w-full bg-slate-50">
  <header class="flex flex-none justify-center">
    {{ partial "header.html" . }}
  </header>
  <main class="flex flex-auto justify-center">
    {{ block "main" . }}{{ end }}
  </main>
  <footer class="flex flex-none justify-center">
    {{ partial "footer.html" . }}
  </footer>
</body>
</html>

I use {{ partial "head.html" . }} to include the content required by the head tag, and refer to the CSS file generated earlier in head.html:

<!-- Theme CSS (/static/main.css) -->
<link rel="stylesheet" href="{{ "main.css" | relURL }}" />

In the HTML body tag, the header tag is the top navigation, the footer tag is the bottom menu, and the main tag is the main content.
The content of {{ block "main" . }}{{ end }} in the main tag needs to be defined on other pages. For example, the simplified list.html code is as follows:

{{ define "main" }}
  <div class="flex flex-col w-full max-w-4xl lg:max-w-5xl relative">
    <div class="flex flex-row">
      <section class="flex flex-col w-2/3">
        {{ range (.Paginate $pages).Pages }}
          <article class="flex flex-col gap-y-3 p-6 mt-6 rounded-lg shadow-md bg-white">

            <h2 class="text-4xl font-semibold text-slate-800">
              <a href="{{ .RelPermalink }}">{{ .Title | markdownify }}</a>
            </h2>
          </article>
        {{ end }}
      </section>
      <aside class="flex flex-col w-1/3 mx-3 top-0 sticky self-start">
        {{ partial "sidebar.html" . }}
      </aside>
    </div>
    {{ partial "pagination.html" . }}
  </div>
{{ end }}

Among them, the section tag corresponds to the article list block, and the aside tag corresponds to the side term display block.
The content of the single page single.html is similar, including the article title, TOC content, article body, etc.
The advantage of tailwindcss is that there is a ready-made typography plugin that can directly render the content of the article without having to define complex CSS styles additionally.

The overall reference relationship can refer to the following figure:

In order to reuse some components, such as tag lists, reading time, icons, etc., we can abstract the same content and put it in the layouts/partials directory.
Taking icons as an example, I use https://tabler.io/icons as the source of icons,
Download the corresponding icon SVG file to the assets directory and define a partial page:

{{- $iconFile := resources.GetMatch (printf "icons/%s.svg" .) -}}
{{- if $iconFile -}}
    {{- $iconFile.Content | safeHTML -}}
{{- else -}}
    {{- errorf "Error: icon '%s.svg' is not found under 'assets/icons' folder" . -}}
{{- end -}}

Among them, the symbol . is the passed icon name parameter, so that we can quickly refer to the icon in the page, such as

{{ partial "icon" "calendar" }}

Through about 5 days of spare time development (#bf54ab9),
the final effect is as follows:

Of course, this is the first phase of the content, only with a white theme (the theme switch button does not respond when clicked), no multilingual support, and no responsiveness.
But the main page structure is already there, and tailwindcss has shown its efficient and flexible characteristics in dealing with CSS styles.

Create a Hugo Theme from Scratch - III

Xiaoliang Wang — Tue, 15 Oct 2024 09:00:00 +0000

This is a blog series that documents my journey of building a Hugo theme https://github.com/tomowang/hugo-theme-tailwind from scratch. The entire series consists of four articles, and this is the third:

Dark Mode

tailwindcss makes handling dark mode very convenient. Based on the original light theme, we only need to set the display style under the dark theme through the dark: prefix.

Add the darkMode: 'class' configuration in tailwind.config.js, and then we can modify the styles in the theme.
For details on dark mode, please refer to the official documentation: https://tailwindcss.com/docs/dark-mode

It's worth mentioning the dark mode toggle button. To keep the theme as simple as possible and avoid referencing additional front-end frameworks,
I researched some common theme button toggle examples in tailwindcss and found that using input + peer + group could achieve the desired effect very well.
The code is as follows:

<div class="darkmode-toggle flex flex-none ml-2">
  <label class="flex items-center px-3 cursor-pointer rounded-full bg-gray-100 dark:bg-gray-600">
    <input type="checkbox" class="sr-only peer">
    <div class="group flex flex-row gap-1 justify-center h-8 px-1 rounded-full bg-white dark:bg-gray-700">
      <i class="h-6 w-6 flex-none rounded-full bg-yellow-400 place-self-center peer-checked:group-[]:invisible">
        {{ partial "icon" "brightness-down" }}
      </i>
      <i class="h-6 w-6 flex-none rounded-full place-self-center invisible peer-checked:group-[]:visible">
        {{ partial "icon" "moon-stars" }}
      </i>
    </div>
  </label>
</div>

I use <input type="checkbox"> to control the theme variable, and then define a group of icons using <div class="group">. Each icon uses peer-checked:group-[]:invisible and peer-checked:group-[]:visible to control visibility and hiding.
This way, I only need to pay attention to the value of the checkbox, while the icon switching of the button is completely handled by tailwindcss.

const themeToggle = document.querySelector('.darkmode-toggle input');

themeToggle.addEventListener('change', function () {
  if (this.checked) {
    localStorage.theme = dark;
    document.documentElement.classList.add(dark);
  } else {
    localStorage.theme = light;
    document.documentElement.classList.remove(dark);
  }
});

Regarding group and peer, tailwindcss describes them as:

The dark theme implementation took me a day of spare time, and the final code is at #75c6b41.

Responsive Design

tailwindcss also makes responsive design easy to use. My goal is to support both mobile and PC. When designing with mobile-first in mind,
tailwindcss uses prefix-less components to design mobile styles first, and then uses prefixed components (e.g., md:) to override styles at other screen sizes. My modifications are as follows:

index ad2e93f..e5b7d76 100644
--- a/layouts/_default/list.html
+++ b/layouts/_default/list.html
@@ -15,9 +15,9 @@

   <div class="flex flex-col w-full max-w-4xl lg:max-w-5xl relative">
     <div class="flex flex-row">
-      <section class="flex flex-col w-2/3">
+      <section class="flex flex-col w-full md:w-2/3">
         {{ range (.Paginate $pages).Pages }}
-          <article class="flex flex-col gap-y-3 p-6 mt-6 rounded-lg shadow-md bg-white dark:bg-gray-700">
+          <article class="flex flex-col gap-y-3 p-6 mt-6 mx-2 md:mx-0 rounded-lg shadow-md bg-white dark:bg-gray-700">
             <h2 class="text-4xl font-semibold text-slate-800 dark:text-slate-200">
               <a href="{{ .RelPermalink }}">{{ .Title | markdownify }}</a>
             </h2>
@@ -40,7 +40,7 @@
           </article>
         {{ end }}
       </section>
-      <aside class="flex flex-col w-1/3 mx-3 top-0 sticky self-start">
+      <aside class="hidden md:flex flex-col md:w-1/3 mx-3 top-0 sticky self-start">
         {{ partial "sidebar.html" . }}
       </aside>
     </div>

As the code shows, I changed the section tag to w-full by default and then used md:w-2/3 to display 2/3 width on larger screens.

The final code is at #279de84.

Multilingual Support

Hugo natively supports multiple languages. First, we need to introduce configuration for multiple languages in the configuration file. For example, our example site has the configuration file exampleSite/config/_default/languages.toml, with the content:

[en]
  languageCode = 'en-US'
  languageDirection = 'ltr'
  languageName = 'English'
  weight = 1
  [en.menu]
  [[en.menu.main]]
    identifier = "post"
    name = "Post"
    pageRef = "post"
    weight = 10

  [[en.menu.main]]
    identifier = "about"
    name = "About"
    pageRef = "about"
    weight = 20

[zh-cn]
  languageCode = 'zh-CN'
  languageDirection = 'ltr'
  languageName = '中文'
  weight = 2
  [zh-cn.menu]
  [[zh-cn.menu.main]]
    identifier = "post"
    name = "文章"
    pageRef = "post"
    weight = 10

  [[zh-cn.menu.main]]
    identifier = "about"
    name = "关于"
    pageRef = "about"
    weight = 20

Then, we need to organize and place the previously hardcoded strings in the theme into the i18n folder and modify the strings in the theme using the i18n function for replacement.
For example, part of the strings in the layouts/404.html file:

diff --git a/layouts/404.html b/layouts/404.html
index 77d8885..32ec853 100644
--- a/layouts/404.html
+++ b/layouts/404.html
@@ -2,11 +2,11 @@
   <main class="grid place-items-center w-full min-h-full max-w-4xl lg:max-w-5xl px-6 py-24">
     <div class="text-center w-full">
       <p class="text-base font-semibold text-indigo-600 dark:text-indigo-300">404</p>
-      <h1 class="mt-4 text-3xl font-bold tracking-tight text-slate-800 dark:text-slate-200 sm:text-5xl">Page not found</h1>
-      <p class="mt-6 text-base leading-7 text-slate-400">Sorry, we couldn't find the page you're looking for.</p>
+      <h1 class="mt-4 text-3xl font-bold tracking-tight text-slate-800 dark:text-slate-200 sm:text-5xl">{{ T "404.page_not_found" }}</h1>
+      <p class="mt-6 text-base leading-7 text-slate-400">{{ T "404.sorry" }}</p>
       <div class="mt-10 flex items-center justify-center gap-x-6">
         <a href="/" class="rounded-md bg-indigo-600 px-3.5 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600">
-          Go back home
+          {{ T "404.go_back_home" }}
         </a>
       </div>
     </div>

Finally, adjust the navigation bar to add a language switch button and a language list.

For the complete code, please refer to #0244464.

Additional Benefits

My native language is Chinese, and I can read English quite well, so I initially only implemented Chinese and English.
But how can I add more languages to the theme? 2023 was a year of significant growth for large language models,
and with the help of LLMs, I translated the language files into more languages like Russian and Japanese using prompts.

Here, I used the gemini interface to process the i18n files:

import google.generativeai as genai

# get key from https://makersuite.google.com/app/apikey
GOOGLE_API_KEY = 'YOUR_GOOGLE_API_KEY'
genai.configure(api_key=GOOGLE_API_KEY)
model = genai.GenerativeModel('gemini-pro')

prompt_template = '''You are a translator and your task is to translate l10n file to different languages.
The l10n file is provided in TOML format. The file contains {{ KEY }} for variables and use
`one` for singular and `other` for plural.

The TOML file is quoted in triple backtick. Please translate the content to {lang}
and keep the original content structure, also remove triple backtick in output:

~~~toml
{en_file_content}
~~~
'''

en_file_content = ''
with open('./en.toml', 'r') as f:
    en_file_content = f.read()

prompt = prompt_template.format(lang='Chinese', en_file_content=en_file_content)

response = model.generate_content(prompt)
print(response.text)

Note the ~~~ in code is used for rendering, since Markdown here in dev.to does not support nested code block.

In the prompt, I included some hugo and code-related instructions, like the file format is TOML, using {{ KEY }} for variables,
and handling singular and plural with onefor singular andotherfor plural.
I also used instructions to ensure the LLM output retained the original format. I tested with Chinese, which I'm familiar with, and the above code output the following:

table_of_contents = "目录"
open_main_menu = "打开主菜单"
open_lang_switcher = "打开语言切换器"
[reading_time]
  one = "阅读时长一分钟"
  other = "阅读时长{{ .Count }}分钟"

[header]
darkmode_toggle = "切换深色模式"

[404]
go_back_home = "返回主页"
sorry = "抱歉，找不到您要查找的页面。"
page_not_found = "页面未找到"

[footer]
powered_by = "由{{ .Generator }} {{ .Heart }} {{ .Theme }}提供支持"
copyright_with_since ="{{ .CopyrightSign }} {{ .SinceYear }} - {{ .CurrentYear}} {{ .Copyright }}"
copyright_wo_since ="{{ .CopyrightSign }} {{ .CurrentYear}} {{ .Copyright }}"

[paginator]
newer_posts = "较新的文章"
older_posts = "较早的文章"

[taxonomies]
categories = "分类"
tags = "标签"
series = "系列"

The final result was quite good. The file structure was correct, and the variables were preserved. I used a similar method to generate localization files for other languages. Of course, I don't actually speak Russian, Japanese, etc., so I couldn't accurately judge the quality of the translations.

Others

Shortcodes

Hugo provides shortcodes to extend markdown rendering capabilities. shortcodes are reusable code snippets that can make editing markdown more efficient. Hugo has some built-in common shortcodes, like figure, gist, etc. You can refer to https://gohugo.io/content-management/shortcodes/.

Some of my blogs use asciinema to record terminal interactions, and I use shortcodes to conveniently embed asciinema.
Hugo searches for shortcodes code in a specific order, with the file name being the final name used in markdown:

/layouts/shortcodes/<SHORTCODE>.html
/themes/<THEME>/layouts/shortcodes/<SHORTCODE>.html

I created the layouts/shortcodes/asciinema.html file and referenced the official embedding documentation:
https://docs.asciinema.org/manual/server/embedding/#inline-player. I wrote the following content in the html:

{{ $id := .Get 0 }}

<script async id="asciicast-{{ $id }}" src="https://asciinema.org/a/{{ $id }}.js"></script>

where .Get 0 means getting the first parameter. Of course, you can also use named parameters. The usage is:

{{</* asciinema 239367 */>}}

The effect is as follows:

Render Hooks

Hugo uses goldmark to render markdown, and render hooks allow developers to override the rendering of specific components. Currently supported are:

image
link
heading
codeblock

Simply, we can add additional attributes to the a tag rendered by the link to ensure security. For example, add the file
layouts/_default/_markup/render-link.html with the content:

<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>

This code adds the rel="noopener" attribute when rendering links to external sites.

Of course, more complex operations can be added to the rendering of images, such as lazy loading, scaling images to fit different resolutions,
and converting images to compressed formats. You can refer to the processing in layouts/_default/_markup/render-image.html.

Code Block Syntax Highlighting and Copying

Hugo uses chroma for code highlighting. It works well with the default configuration, but I want to go further,
such as having the code block theme switch along with the light and dark modes, and providing code block copying functionality.

To support custom styles, we need to adjust the code highlighting configuration in the config/_default/hugo.toml file to use CSS classes to apply highlighting styles:

[markup.highlight]
  noClasses = false

Then use the command to generate code highlighting styles for our light and dark themes:

hugo gen chromastyles --style=solarized-light
hugo gen chromastyles --style=solarized-dark

Write the styles into the main style file. For the dark theme, you can use the column editing mode of the IDE to add .dark before each line of style to restrict it.
The effects under light and dark themes are as follows:

However, in some cases, chroma's default CSS styles may conflict with tailwindcss's typography plugin. For example, when the line number configuration is enabled, you will find that there is a large gap between the code line numbers and the code block:

This is because chroma uses table elements when rendering line numbers, while typography adds additional margins to pre elements.
In this case, we need to find the conflict points and then override some styles. The following CSS styles will remove the margins and border-radius of the pre elements in code blocks with line numbers and change the display property of the table:

/* fix highlight with line number */
.highlight .chroma .lntable {
  margin: 1.7142857em 0;
  padding: 0.8571429em 1.1428571em;
  border-radius: 0.375rem;
  overflow: hidden;
}

.highlight .chroma .lntable pre {
  margin: 0;
  padding: 0.8571429em 0;
  border-radius: 0;
}

/* https://caniuse.com/css-has */
.highlight .chroma:has(table) {
  background-color: transparent;
}

.highlight .lntable tr {
  display: flex;
}

.highlight .lntable tr .lntd:last-child {
  flex-grow: 1;
}

Code block copying is achieved by checking if there are pre elements on the page, then finding the .highlight elements on the page, and adding corresponding copy buttons.
I used the statement {{- if (findRE "<pre" .Content 1) }} in baseof.html to search for elements,
which reduces JavaScript loading. Additionally, note that code blocks with line numbers will render two code elements, and we need to take the last one.
Relevant code can be found at #4d62bba
and #df6ac6d.

Pipes

When allowing users to modify the theme, we need to keep the original CSS and JavaScript code.
But for general direct users, we need to shield these code compilation logic while ensuring that the final generated static resources are compressed.
Here we can use the pipes feature provided by Hugo.
For tailwindcss, I initially placed the original CSS style in assets/css/main.css, the compiled code in the static folder static/main.css, and directly referenced the static file in head.html:

<!-- Theme CSS (/static/main.css) -->
<link rel="stylesheet" href="{{ "main.css" | relURL }}" />

I wanted to display the original CSS style during development but use the compressed version with a hashed filename when deployed.
Ultimately, I adjusted the location of the CSS files, placing both the pre-compiled and post-compiled CSS code in assets/css
(so that Hugo can process the resources), and adjusted the inclusion of CSS files:

{{- $styles := resources.Get "css/index.css" -}}
{{- $env := getenv "HUGO_THEME_DEVELOPMENT" -}}

{{- if eq $env "true" }}
  {{- $styles = resources.Get "css/main.css" | postCSS (dict "config" "./postcss.config.js") -}}
{{ end -}}

{{- if hugo.IsDevelopment }}
  {{- $styles = $styles | resources.ExecuteAsTemplate (printf "css/main.dev.%v.css" now.UnixMilli) . -}}
{{ else }}
  {{- $styles = $styles | minify | fingerprint -}}
{{ end -}}
<link rel="stylesheet" href="{{ $styles.RelPermalink }}">

Here, I use HUGO_THEME_DEVELOPMENT to identify the theme development mode, and process CSS styles using PostCSS in theme development mode.
When using the hugo server command, Hugo is in development mode, hugo.IsDevelopment is true,
and filenames with timestamps are used in development mode to prevent caching. In production mode, | minify | fingerprint is applied for compression and file caching.

Regarding the environments corresponding to different Hugo commands, you can refer to the following table:

Command	Environment
`hugo`	`production`
`hugo --environment staging`	`staging`
`hugo server`	`development`
`hugo server --environment staging`	`staging`

Similarly, we can handle JavaScript files in a similar way, such as for code block copying:

{{- $jsCopy := resources.Get "js/code-copy.js" | js.Build "code-copy.js" -}}
{{- if not hugo.IsDevelopment }}
  {{- $jsCopy = $jsCopy | minify | fingerprint -}}
{{ end -}}
<script src="{{ $jsCopy.RelPermalink }}"></script>

Lighthouse

I've completed most of the code writing, but I still need to check if the pages rendered by my theme conform to some standards and best practices.
I used the built-in lighthouse developer tool in chrome to check the site.

It can be seen that the performance score of the site is good, but there is room for improvement in accessibility and SEO. For example, the contrast of some colors in the theme, the alt attribute of images, etc.

Based on lighthouse's suggestions, I made adjustments and optimizations for each suggestion, and finally, the lighthouse score reached a high level:

Create a Hugo Theme from Scratch - I

Xiaoliang Wang — Tue, 15 Oct 2024 09:00:00 +0000

This is a series of blog posts documenting the process of building a Hugo theme from scratch: https://github.com/tomowang/hugo-theme-tailwind. The series includes four parts, and this is the first one:

Background

As a developer with over ten years of experience, I've been exposed to various technologies, including frontend, backend, big data, and machine learning. When I wanted to share my personal development projects and life experiences, I decided to build a blog site.

During my initial search for a blogging platform, I considered options like WordPress, Hexo, Jekyll, and others. Ultimately, I chose Hugo for its static page generation capabilities, and I picked a nice domain name for my blog: tomo.dev.

The reason for choosing Hugo was simple. It's developed in golang, making installation and build times fast. It's open-source, has a well-established community, comprehensive official documentation, and a wide variety of open-source themes. Choosing a theme for your site can be a headache, but after browsing through numerous themes on the official theme site, I finally settled on a theme called hello friend.

hello friend has a clean page structure, relatively simple code, and supports dark mode and responsive design. I eventually wrote my first blog post: https://tomo.dev/posts/blog-using-hugo/.

During the subsequent blogging process, I added some features and adjusted the page structure of the hello friend theme. For example, I added my GitHub address to the bottom navigation, modified some JavaScript code, and added some new third-party JavaScript libraries.

My native language is Chinese, and all my articles are written in Chinese. The blog didn't receive much traffic for two years after its launch. In the latter half of 2023, I started to get involved in web site promotion, such as SEO. So I thought about translating my blog into English and doing some SEO experiments.

However, the hello friend theme itself doesn't support multilingualism and its code is no longer maintained (although I later discovered a successor called hello friend ng). Additionally, I had been away from frontend development for a while and learned that tailwindcss was quite popular. Wanting to catch up with the latest frontend trends, I decided to build my own theme.

Features

Building a theme and using one are two completely different modes. When using a theme, most of the time you only need to understand simple configurations and be familiar with markdown syntax. However, building a theme is like developing a small product or plugin, and I had to answer the following questions:

What will be the theme's style and layout?
What features should it have?
What technical skills are required?
How to publish, promote, and make it accessible to more people?

I'm not a product manager or a designer, but there are many open-source themes available for reference. I wanted my theme to have a clean layout like hello friend, minimize the use of complex frontend technologies, be easily extensible, and SEO-friendly.

Regarding technology, tailwindcss was a clear choice. I had used frontend component libraries like bootstrap, vuetify, and ant design, so learning a new CSS library shouldn't be too difficult. As for Hugo theme-related technologies, I knew I needed some knowledge of html/template syntax in golang, and the rest I could look up in the official documentation as needed.

Finally, I referenced some existing themes and the tailwindcss example site to draw a simple page layout diagram, including a logo, navigation menu, multilingual switcher, dark mode switcher, article list, term display block, social media links in the footer, and copyright information.

Based on the prototype, I outlined the main features:

[ ] Basic features: navigation and menu, list page, article page, right-side category list, and category list and detail pages
[ ] Darkmode - dark theme switcher
[ ] Responsive design
[ ] Multilingual support
[ ] Image processing
[ ] Social media links in the bottom navigation

And other supporting features and hidden needs for open-source projects:

[ ] Continuous integration
[ ] Documentation and configuration examples
[ ] Lighthouse score
[ ] Others
- [ ] Experimenting with shortcodes
- [ ] Google Analytics configuration
- [ ] User comment functionality
- [ ] Social tags
- [ ] Code block copy functionality

Then I needed to give the theme a name. After browsing the official theme list, I finally chose hugo-theme-tailwind. It turns out that a good name can bring some extra exposure and traffic to the project.

I initialized the GitHub repository and submitted the first commit #d833043.

Development Environment Setup

To build a new Hugo theme, we need Hugo and Node.js. Installation of these tools is not the focus of this series, you can refer to the official documentation:

hugo - https://gohugo.io/installation/
nodejs environment - I use fnm and pnpm

With the Hugo command, execute the following command in the repository directory:

hugo new theme hugo-theme-tailwind

This command creates a folder themes/hugo-theme-tailwind in the current directory. We need to move it to our repository and remove the theme's default content directory.

mv themes/hugo-theme-tailwind/* .
rm -rf themes/
rm -rf content

Download the official example site content to the theme's exampleSite directory

git clone https://github.com/gohugoio/hugoBasicExample.git exampleSite
rm -rf exampleSite/.git

Add the theme configuration in the example site's configuration file: theme = "hugo-theme-tailwind", and then run the command:

hugo server -s exampleSite --gc --themesDir=../..

This command starts the Hugo server, allowing us to test the initial rendering of the theme. The sample log output is as follows:

Start building sites …
                   | EN
-------------------+-----
  Pages            | 41
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  2
  Processed images |  0
  Aliases          |  9
  Sitemaps         |  1
  Cleaned          |  0

Built in 13175 ms
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Visit http://localhost:1313/ to see a simple page as shown below:

Now we have a simple, runnable initial theme and example site. I will expand and rewrite based on this basic theme in the following sections.