Migrate to v3

Migrate to v3

This guide will help you migrate your existing v2 project to v3. It will cover the most common changes you will need to make to your project to get it working with v3.

Introduction

Around the end of 2017, I was planning to start my own blog. I came across Hugo, which is very fast, and it subverted my idea of using Node.js Hexo to build a blog. At the same time, I didn't want to use existing themes, I wanted to write my own theme from scratch, because I thought it was a unique experience. I named it Dream, which represents my little dream. I was still an intern at that time, just starting to work, I learned it in my spare time, and finally developed the first version of the theme. In my current opinion, the design is not that good-looking, but I can still understand my mood at that time, I was excited and full of accomplishment at that time.

Later, as my technology improved, I gradually overturned my previous design. I think this process is also inevitable. As a person grows, his level and quality will gradually improve, so he will naturally have the idea of wanting to modify his early works. So, I started my v2.0 action, I used masonry layout to reconstruct Dream, because I particularly liked this irregular arrangement structure at that time, I think it is very good to display my articles in this form. From this stage on, my theme was gradually discovered by more and more people, and many people also started to use my theme, and they also raised many questions, and I would also fix it synchronously. In this way, Dream has continuously added more parameters, and on the basis of masonry layout, there are more customizable display forms.

But later, due to my loss of motivation to write a blog (there are many reasons, the COVID-19, work, life troubles, etc.), the maintenance of Dream has gradually become deserted. I have tried many times to modify some places before, but in the end it all came to nothing (for example, I once wanted to use Bulma to replace the outdated and no longer maintained Semantic UI). Just like I lost my motivation to write a blog, it is also very difficult for me to complete other things, I became very anxious, it was the kind of anxiety of growth, which makes you no longer able to concentrate and wholeheartedly do one thing. Time is all fragmented.

Around the beginning of this year (2024), when I saw my blog again (I rarely looked at it myself before), I thought I should make some changes. I want to pick up my blog again, and not just it, I want to pick up every unfinished thing I have done. I have already passed a lot of my youth, and I don't want to waste it anymore. But it is easy to think, but it is still very difficult to do. I started to rebuild Dream, I used three new things: tailwindcss, daisyUI and Alpine.js, to replace the old technology stack. These are all new things I have come into contact with in the past few years. I combine them with Hugo, so that Hugo can both maintain its speed and have stronger rendering capabilities. At the same time, I also adopted a new design. Before, I added a lot of parameters, but I didn't think carefully about whether they were "meaningful" modifications. As a theme, my current idea is to be ready to use without making too many modifications. This may be the original intention of a theme. To make a durable and durable design, not a fancy design, is more in line with my current ideas. This reconstruction is also a summary of my 7 years of aesthetics, design and technology.

Time came to the beginning of July, and I finally completed the reconstruction, which is a new milestone version. I have not only completed the modification of the theme, but also completed the writing of the documentation. I want to make it very good in every aspect. This is also my commitment to myself. I want to complete every task completely. This is just the beginning of all subsequent things. I hope you will like Dream's latest design. If you encounter any problems during use, please feel free to raise them in the issues (opens in a new tab), and I will check them in time.

The following content will help you migrate from v2 to v3. You can compare it one by one to make modifications. Similarly, if you encounter any migration issues, please feel free to raise them at any time.

Params Changes

Some params have been changed in v3. You can compare the following sections to make modifications.

copyright

The old copyright = "" has been removed, it used to be used to display copyright on the About page. Now you can add a copyright file directly into the content/about folder, and it will be displayed on the About page:

hugo new about/copyright.md

Colors and Dark Mode

There're many color params in v2, but in v3, all params below have been removed:

# background = ""
# linkColor = "seagreen"
 
# dark mode
# defaultDark = true
# backgroundDark = "black"
# darkLinkColor = "darkseagreen"
# darkNav = true
# dark404 = true

Currently, Dream uses daisyUI to provide some out-of-box themes (opens in a new tab) to use in light and dark mode.

Please view Light and Dark Mode for more details.

Tags and Categories

If you have the following params specified, you can safely remove them:

# maxTags = 5
# categoriesLimitInHeader = 6 # deprecated
# headerBottomText = "" # deprecated

Social Links

Old specific social links have been removed:

# twitter = ""
# facebook = ""
# instagram = ""
# mastodon = ""
# linkedin = ""
# github = ""
# stackoverflow = ""
# codepen = ""

Refer to Social Links for the updated configuration.

highlightjs

hightlight.js has been deprecated in favor of Hugo built-in syntax highlighting, you can safely remove the following params:

# highlightjs = true
# highlightjsCDN = "https://cdn.jsdelivr.net/gh/highlightjs/cdn-release/build/highlight.min.js"
# highlightjsExtraLanguages = ["ocaml"]
# highlightjsTheme = "gruvbox-light"
# highlightjsThemeDark = "gruvbox-dark"

If you want to custom the syntax highlighting, please refer to Syntax Highlighting.

Customizing the syntax highlighting is recommended if you have code blocks in your posts.

Search

The old search has been removed, you can safely remove the following params:

# search
# enableSearch = true

The new way to add search functionality is described in Search.

Other options

Below are some other options that have been removed, you can safely remove them:

# reversePostAndAside = true
# shareInAside = true
# fixedNav = true
# collapsibleTags = true
# collapseBySummary = true
# disableFlip = true
# hideBackSocialLinks = true

Almost Done

I hope this guide has helped you migrate your project to v3 successfully.

I may ignore some deprecated params, if you encounter any problems, please feel free to raise them in the issues (opens in a new tab), thank you very much!

Wish you a happy journey with Dream v3! 🎉