🔧 Create a Hugo Theme from Scratch - III
Nachrichtenbereich: 🔧 Programmierung
🔗 Quelle: dev.to
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:
- 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
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 one
for singular and
otherfor 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:
{{< asciinema 239367 >}}
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
📈 45.78 Punkte
🔧 Programmierung
🔧 Create a Hugo Theme from Scratch - II
📈 45.78 Punkte
🔧 Programmierung
🔧 Create a Hugo Theme from Scratch - IV
📈 45.78 Punkte
🔧 Programmierung
🔧 How to Create a WordPress Theme from Scratch
📈 27.43 Punkte
🔧 Programmierung
🔧 Create contact form with hugo
📈 24.58 Punkte
🔧 Programmierung
🐧 Linux from scratch vs docker scratch?
📈 24.17 Punkte
🐧 Linux Tipps
🐧 KDE.org migrated to Hugo
📈 18.34 Punkte
🐧 Linux Tipps
🪟 Hugo Barra wird Oculus-Chef bei Facebook
📈 18.34 Punkte
🪟 Windows Tipps
🐧 [$] Hugo: a static-site generator
📈 18.34 Punkte
🐧 Linux Tipps
📰 Hugo Boss will Online-Geschäft massiv ausbauen
📈 18.34 Punkte
📰 IT Nachrichten
🔧 How to Host Hugo in Vercel
📈 18.34 Punkte
🔧 Programmierung
🔧 Hugo- The Best Static Site Generator
📈 18.34 Punkte
🔧 Programmierung