Building a Personal Blog with Hugo (2)
Picking up where we left off, the previous post briefly covered how to install and use Hugo. But stopping right there would feel a bit thin.
To ensure a good writing experience and stay focused on producing content, it’s worth spending more time up front — only then will you get twice the result with half the effort later. So this post goes deeper into optimization.
I’d like to thank the bigshot Sulv for the generous help. His blog: https://www.sulvblog.cn/
Hugo Directory Overview
First, let me introduce the directories that Hugo generates when creating a new site and what they do, so you have a sense of direction for the operations below. A website generated with Hugo contains the following files and folders:
- archetypes: stores
.mdtemplate files; this folder takes priority over the/archetypesfolder in the theme - config.toml: the configuration file
- content: stores all the content of the site
- data: stores data files for templates to use
- layouts: stores
.htmltemplates; this folder takes priority over the/layoutsfolder in the theme - static: stores static files such as images, css, and js; files in this directory are copied directly to
/public, and this folder takes priority over the/staticfolder in the theme - themes: stores themes
- public: stores the generated static files after running the
hugocommand
Steps
1. Edit config.yml
The config.yml file is the configuration for the whole site. It tells Hugo how to build the site, such as global parameters and menus. The file defaults to toml format; in the previous article, the -f yml argument in the Generate Site section of the commands changed the default configuration file to yaml format.
- The default configuration provided by the official docs: Sample config.yml
- For the meaning of the parameters, refer to the theme Wiki: Features, Variables, as well as the relevant content in the official Hugo docs: Configure Hugo.
- The configuration file used here is the one given by Sulv; thanks again to Sulv. The content of the configuration file needs to be modified according to your actual situation; the main thing is to change site identifiers such as links and titles to your own. Also,
logo.gifshould be placed atstatic/img/logo.gifin the site’s root directory.
| |
2. Configure the 🔍 Search Page
Original reference: Search Page
PaperMod uses Fuse.js Basic to implement the search functionality
The search functionality is already enabled in the configuration file. You need to create a search.md containing the following content in the content/ directory in the site’s root. Additionally, you can customize it to your needs by referring to the theme documentation.
| |
To hide a specific page from search, add the following to its front matter (the content enclosed by the two --- lines at the top):
| |
3. Configure the ⏱ Timeline Page
Original reference: Archives Layout
The ⏱ Timeline page is the Archives Layout. The archive functionality is already enabled in the configuration file. You need to create an archives.md containing the following content in the content/ directory in the site’s root. Additionally, you can customize it to your needs by referring to the theme documentation.
| |
4. Configure the 🔖 Tags Page
- The default language set in
config.ymlis Chinese, and support for other languages is not enabled. If needed, you can customize it yourself by referring to the official docs: Translations, Multilingual Mode . However, the🔖 Tagspage is not controlled by this setting, so you need to modify the corresponding html template yourself. - Also, regarding the default language: the theme supports multilingual, meaning it provides some translations for its built-in page templates, e.g.
Home->主页. The files that provide multilingual support are inthemes/PaperMod/i18n/, wherezh.yamlis Simplified Chinese. - To prevent your modified files from being reverted when updating the theme, make the modifications in the site’s root directory, so they can override the theme’s original files.
Once you understand the three points above, you can start the following modifications.
4.1. Modify the default translations
Create an i18n/ folder in the site’s root, copy themes/PaperMod/i18n/zh.yaml to i18n/zh.yaml, and edit it
| |
Change it to the following content:
| |
4.2. Modify the html template
The template file for 🔖 Tags is themes/PaperMod/layouts/_default/terms.html. Follow the same steps as above: create a layouts/_default/ folder in the site’s root, copy themes/PaperMod/layouts/_default/terms.html to layouts/_default/terms.html, and edit it
| |
Change it to the following content:
| |
5. Customize the front matter
Hugo provides a default template for generating articles. When you use hugo new content/posts/demo.md to generate a new page, it provides the most basic front matter, located at archetypes/default.md, with the following content:
| |
This template only contains the three required parameters: title, date, and draft (whether it is a draft?). For writing convenience, here is a template provided by the bigshot Sulv, which I have slightly modified.
Create a new archetypes/post.md and edit it,
| |
Paste the following content:
| |
6. Configure the 🙋🏻♂️ About Page
In the previous section we configured the article generation template. Below I’ll show how to use the template to generate the 🙋🏻♂️ About page (about.md).
First, generate about.md in the content/ directory
| |
You’ll see an about.md with the template content; modify the front matter parameters according to the comments and your own needs.
Then, starting at the very bottom, write the body using Markdown syntax to complete your own 🙋🏻♂️ About page
7. Content Management from Novice to Pro
The Hugo Directory Overview section introduced the paths in the site and their purposes. So where do we put our finished articles? The answer is the content/ directory.
The official docs Content Management explain in detail everything you need to know about managing blog content. Below I’ll cover what we need to know for now.
- Once the blog is live, everything we see is Markdown files in the
content/directory. Thecontent/directory is the top-level directory that manages all the site’s content; it generally serves as the site’s homepage, with an access URL of: http://example.com. Also, files likeabout.md,archives.md, etc. are usually stored here. - For a Markdown file created in the
content/directory, e.g.about.md, its access URL is: http://example.com/about/ . You may notice it has no extension. In Hugo the default behavior is to present content using Pretty URLs (Pretty URLs), i.e. the “.html” extension is omitted from links. If you have a peculiar taste, you can setuglyurls: trueinconfig.ymlto enable the Ugly URLs (Ugly URLs) environment variable, and the access URL will become: https://example.com/about.html/ - For a directory created in the
content/directory, e.g.posts(by convention we store our blog articles under this path), its access URL is: http://example.com/posts/ , and other directories work the same way.- In my blog, I created the following paths:Where
1 2 3 4 5 6 7 8 9 10 11 12 13 14content ├── about.md ├── archives.md ├── posts │ ├── _index.md │ ├── life │ │ └── _index.md │ ├── read │ │ └── _index.md │ └── tech │ ├── 1st.md │ ├── 2nd.md │ └── _index.md └── search.mdposts/life/corresponds to🏖 Life;posts/read/corresponds to📕 Reading;posts/tech/corresponds to👨🏻💻 Tech. - Let me emphasize here:
_index.md. The official reference is Index Pages. In short, this file exists as a custom index page. Here’s one I use as a reference:1 2 3 4 5 6 7 8 9--- title: "📚文章" # description: "知识是学习来的，经验是总结来的。" hidemeta: true # 是否隐藏文章的元信息，如发布日期、作者等 --- 知识是学习来的，经验是总结来的。 <!--\more--> # 此处的“\”用于转义，否则无法正常显示，实际使用须删去。
- In my blog, I created the following paths:
Final Words
At this point, the basic configuration of Hugo is essentially complete, and you can focus on creating. If you need more freedom or have other needs, you can also do deep customization. In the next section, I’ll introduce some Hugo writing workflows, a few additional usage tips, and share the script I use to back up Hugo with a Tianyi cloud drive.