Hugo boasts a number of excellent themes, for academic themes, you can refer to . For the installation and configuration of the academic theme, please refer to its README document. This article will delve into advanced Hugo configuration and customization. After reading this blog post, you will gain a deeper understanding of Hugo and be able to complete some customizations:

  • Adjusting article templates
  • Personalization - Integrating Live2D widget
  • Personalization - Supporting embedded Bilibili videos in articles
  • Internationalization & CJK

Article Templates

Generally, there are two ways to create new articles. One is to directly copy the existing file directory and make changes, and the other is to use the hugo new command. For example, you can use hugo new content post/{post-path}/ to create an article (the article directory for the academic theme is in content/post, while other themes might have it in content/posts). This command searches for templates to generate content in the following order:

  1. archetypes/
  2. archetypes/
  3. themes/academic/archetypes/
  4. themes/academic/archetypes/

When creating a blog site using the hugo new site {blog-path} command, the default generated directory includes the archetypes/ file with the following content:

title = '{{ replace .File.ContentBaseName "-" " " | title }}'
date = {{ .Date }}
draft = true

This file content is in the Hugo Front matter format, which is toml. We test it using the command hugo new content post/test/, and the generated article content is as follows:

title = 'Test'
date = 2023-11-22T23:53:32+08:00
draft = true

Remove archetypes/ and content/post/test/, and run the command hugo new content post/test/ again. The newly generated article file content will be:

# Documentation:

title: "Test"
subtitle: ""
summary: ""
authors: []
tags: []
categories: []
date: 2023-11-22T23:58:38+08:00
lastmod: 2023-11-22T23:58:38+08:00
featured: false
draft: false

# Featured image
# To use, add an image named `featured.jpg/png` to your page's folder.
# Focal points: Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight.
  caption: ""
  focal_point: ""
  preview_only: false

# Projects (optional).
#   Associate this post with one or more of your projects.
#   Simply enter your project's folder or file name without extension.
#   E.g. `projects = ["internal-project"]` references `content/project/deep-learning/`.
#   Otherwise, set `projects = []`.
projects: []

This allows us to quickly customize the Front matter content.

The academic theme also supports various article templates, such as, publication, etc., which can be found in the themes/academic/archetypes directory. For example, to create a new Courses section, you can use the command hugo new content --kind docs courses/linux-programming/ This command applies the themes/academic/archetypes/ layout, and you can view the effect locally by visiting http://localhost:1313/courses/ .

Personalization - Integrating Live2D Widget

This section demonstrates how to customize the theme by integrating a Live2D widget (although we are using the academic theme, who doesn’t love anime?).

Template Basic Structure

First, to customize the theme, you need to have a basic understanding of the Hugo theme structure. The academic theme structure is located in the themes/academic/layouts directory:

├── _default
│   └── _markup
├── authors
├── book
├── docs
├── partials
│   ├── comments
│   ├── functions
│   ├── jsonld
│   ├── marketing
│   └── widgets
├── project
├── publication
├── section
├── shortcodes
├── slides
├── talk
└── widget_page

Regarding the site content, it can be roughly divided into list pages and detail pages. List pages are like the course list page /courses/, while detail pages are single pages like /courses/example/. The themes/academic/layouts/_default/ directory is the template entry point, where:

  • baseof.html is the main framework of the site, containing the complete HTML, which loads other page components through Go HTML template syntax to form the final page
  • list.html is for list pages
  • single.html is for detail pages

Both list.html and single.html declare the main body of the page using define "main" and are then referenced in baseof.html using the code {{ block "main" . }}{{ end }}.

Of course, we can see that there is a lot of content in the layout directory. Hugo will load different layouts based on the site content directory structure and the type defined in the Front matter. For example, in the aforementioned courses directory, content/courses/example/ defines type: docs, so the layout under the themes/academic/layouts/docs directory will be applied. The detailed loading mechanism and priority of this part are quite complex. If you are interested, you can refer to the official documentation .

Adding Live2D Widget

Through the code in baseof.html, we can see that the header part of the site HTML is referenced from {{ partial "site_head" . }}. Most themes provide capabilities for user customization, and academic is no exception. By creating custom_head.html, we can extend the theme without modifying the template. The reference relationship is as follows:

│                                     │
│         _default/baseof.html        │
│                                     │
                   │  {{ partial "site_head" . }}
│                                     │
│        partials/site_head.html      │
│                                     │
                   │ {{ partial "custom_head" . }}
│                                     │
│      partials/custom_head.html      │
│                                     │

Referring to the comments in themes/academic/layouts/partials/custom_head.html, we create the file layouts/partials/custom_head.html in the root directory of the site to override the default custom_head.html file loaded by the theme, and fill it with the following content:

<link rel="stylesheet" href="">
<script src=""></script>
<script src=""></script>
    window.addEventListener('load', () => {
        localStorage.setItem("modelId", 2);  // 2 -> "bilibili-live/22"
            waifuPath: "",
            cdnPath: "",
            tools: ["hitokoto", "asteroids", "switch-model", "switch-texture", "photo", "info", "quit"]

This code loads the style and model of the Live2D widget and executes the relevant initialization code. Ultimately, we can see the Bilibili Live2D widget in the lower left corner, with the following effect:

live2d bilibili model

Live2D widget, derived from Japanese “かんばんむすめ”, refers to a female shop assistant or mascot. The above sample code is referenced from , under the GPL-3.0 license . The model cdnPath parameter is sourced from , and the model copyright belongs to the original author.

Personalization - Supporting Embedded Bilibili Videos in Articles

Markdown can include raw HTML for rendering, allowing us to embed Bilibili videos in the site by embedding HTML. Taking the video as an example, open the video and under it, you can find the sharing menu where you can locate the embed code section.

bilibili share

Click on it to copy the embed code, as follows:

<iframe src="//" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

Of course, if we want to improve efficiency, we can use the shortcode feature provided by Hugo. Hugo itself provides some built-in shortcodes, such as figure, gist, etc. In this section, we will create a bilibili shortcode to achieve the ability to quickly embed Bilibili videos.

Create a file named layouts/shortcodes/bilibili.html in the root directory of the site, and fill it with the following content:

{{- $vid := .Get "id" | default (.Get 0) -}}
{{ $q := "" }}

{{ if strings.HasPrefix (lower $vid) "bv" }}
  {{ $q = querify "bvid" $vid }}
{{ else }}
  {{ $q = querify "aid" $vid }}
{{ end }}

<iframe style="width: 100%; aspect-ratio: 16 / 9;"
    src="//{{ $q | safeURL }}&p=1"
    scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true">

The above code will generate the embed link for the Bilibili video based on the passed video id parameter and set the video width to 100% and the aspect ratio to 16:9 using CSS.

Then we can use the bilibili shortcode in Markdown. First, open the video you want to embed, find the BV-prefixed video ID after video/ in the video URL link, such as BV1kE41147oo in the link, and then embed the code {{< bilibili BV1kE41147oo >}} in the article. The result is as follows:

For more information on using shortcodes, please refer to the Hugo official documentation .

Internationalization & CJK

As an excellent theme, academic supports internationalization configuration. If your site audience includes users from both domestic and overseas, you can enable language switching through internationalization configuration.

The internationalization configuration resides in the config/_default/languages.toml file, which by default only contains English configuration. Add the following code to the configuration file:

  languageCode = "zh-Hans"
  contentDir = "content/zh"
  title = "学术"
    description = "测试中文站点"
    name = "示例"
    url = "#hero"
    weight = 10

    name = "文章"
    url = "#posts"
    weight = 20

    name = "项目"
    url = "#projects"
    weight = 30

    name = "出版物"
    url = "#featured"
    weight = 40

    name = "课程"
    url = "courses/"
    weight = 50

    name = "联系"
    url = "#contact"
    weight = 60

Also, create a zh directory under the content directory and copy the content from the original content directory into the zh directory. Now, you should see the language switching menu in the upper right corner of the site.


After adjusting the content of the corresponding articles in the zh directory, you can see the language switching effect of the site. Switch to Chinese, and you will see that the menu also changes to Chinese accordingly.

cn menu

Hugo is written in Go and uses the goldmark markdown library. By default, markdown will render line breaks as spaces during rendering. When using CJK languages (Chinese, Japanese, Korean), there might be spaces between some words after rendering, as shown below:

space in cjk

We can use the CJK extension provided by goldmark to configure the CJK rendering logic. The configuration file is located at config/_default/config.toml. Find the following section:

  defaultMarkdownHandler = "goldmark"
      unsafe = true  # Enable user to embed HTML snippets in Markdown content.

Add the following code below it:

      enable = true
      eastAsianLineBreaks = true
      escapedSpace = true

Save the file and observe the effect.