Installation

Download the latest Hugo Extension ‘.deb’ file

The extended version of Hugo supports features such as Sass processing and WebP image encoding, and the stack theme used by bloggers needs extended support, so I didn’t use apt to install the standard version of hugo, and downloaded the latest ‘.deb’ file from Hugo’s official GitHub page:

Use ‘wget’ to download the latest Hugo extension ‘.deb’ file:

1wget https://github.com/gohugoio/hugo/releases/download/v0.145.0/hugo_extended_0.145.0_linux-amd64.deb

You can check the latest version by visiting [Hugo GitHub Releases] (https://github.com/gohugoio/hugo/releases) and make sure the download file names include ’extended’ and ’linux-amd64’ (for 64-bit Ubuntu systems).

Install the Hugo extension

Once the download is complete, install the ‘.deb’ file using ‘dpkg’:

1sudo dpkg -i hugo_extended_0.145.0_linux-amd64.deb

If a dependency problem occurs, run the following command to fix it:

1sudo apt-get install -f

Verify that the installation was successful:

1hugo version

The output like ‘hugo v0.145.0-xxx+extended linux/amd64’ indicates that the extended version has been installed successfully.

Precautions
Version Update: Repeat steps 1.1 and 1.2 each time Hugo releases a new version to download and install the latest ‘.deb’ file.
Permission Issues: If you are having permission issues when unpacking Go, run the command with ‘sudo’.
System Architecture: Make sure that the downloaded ‘.deb’ file and Go file match your system architecture.

Install and configure Go

Hugo is written in Go, and while you don’t need Go for normal use, Go is required if you need to use Hugo Modules or compile custom versions. Here are the installation and configuration steps:

Download the latest Go binary:

Visit the download page of the Go official website (https://golang.org/dl/) to find the latest version and download the tarball for Linux:

1cd /tmp
2wget https://go.dev/dl/go1.22.1.linux-amd64.tar.gz

Unzip and install Go:

Extract the file to ‘/usr/local’:

1sudo tar -C /usr/local -xzf go1.22.1.linux-amd64.tar.gz

Configure Go environment variables:

Edit the ‘~/.profile’ file and add the following:

1echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.profile
2echo 'export GOPATH=$HOME/go' >> ~/.profile
3Applying changes:
4
5```bash
6source ~/.profile

Verify Go Installation:

1go version

The output like ‘go version go1.22.1 linux/amd64’ indicates that Go is successfully configured.

Hugo root folder description

Folders/Files	Description	Precautions
`archetypes/`	A content template directory that defines the default front matter	for new files such as ‘hugo new’ ‘default.md’ is included by default, and other templates can be customized
`assets/`	The resource file directory, which stores SCSS, images, etc., is processed by Hugo Pipes (e.g., compiling SCSS to CSS)	Support needs to be configured in ‘hugo.yaml’ (e.g. ‘assets.dir’).
`content/`	A directory of content files that holds Markdown files, organized by type (e.g. ‘content/post/’ for articles)	The file name determines the URL (e.g., ‘my-post.md’ -> ‘/post/my-post/’).
`data/`	A data file directory that holds YAML, JSON, or TOML files for dynamic data (such as navigation menu data). In the template by ‘. Site.Data’ access
`layouts/`	Customize the template directory to override the theme’s default template	Priority is higher than templates of the same name in ’themes/’
`public/`	The generated static site output directory, with the post-build content in this	Each run of ‘hugo’ empties and regenerates the
`static/`	Static file directories, which store images, CSS, JS, etc., are directly copied to the root directory of the site Output directly to ‘public/’	, without Hugo processing
`themes/`	A theme directory that stores downloaded or custom themes (e.g. ‘hugo-theme-stack’). Enable	via the ’theme’ configuration
`hugo.yaml`	Master profile, defining site settings (such as language, theme, URL, etc.)	YAML, TOML, JSON formats are supported

Create a Hugo site and test it

Once you’ve installed Hugo and Go, you can create a simple test environment for your blog site:

Create a new site:

1hugo new site myblog
2cd myblog

Edit the configuration file

  1#在站点的根目录下编辑配置文件,配置文件有toml和yaml格式，
  2#博主使用的yaml格式;下面是hugo.yaml文件的内容，根据需要修改：
  3
  4#博主测试baseURL和baseurl设置不生效，
  5#启动hugo 服务时hugo server --baseURL="https://www.test.com/" 测试可以
  6baseurl: https://www.test.com/ # 网站的根 URL，用于生成绝对链接 实际测试不生效
  7
  8languageCode: en-us # 默认语言代码，设置为英语（美国）
  9theme: hugo-theme-stack # 使用的主题名称，这里是 Stack 主题
 10title: 网站标题  # 网站标题，显示在浏览器标签和页面上
 11copyright: 版权声明 # 版权声明，显示在页面底部
 12
 13pagination:  # 分页设置
 14  pagerSize: 10  # 每页显示的文章数量
 15
 16# languages:  # 多语言支持配置（已注释）
 17#     en:  # 英语配置
 18#         languageName: English  # 语言名称
 19#         title: 网站标题  # 英语版网站标题
 20#         description: Blog  # 英语版网站描述
 21#         weight: 1  # 语言权重，决定显示顺序
 22#     zh-cn:  # 中文配置
 23#         languageName: 中文  # 语言名称
 24#         title: 网站标题  # 中文版网站标题
 25#         description: 博客  # 中文版网站描述
 26#         weight: 2  # 语言权重，决定显示顺序
 27
 28# Change it to your Disqus shortname before using
 29# disqusShortname: stack  # Disqus 评论系统的短名称，需替换为你的 Disqus ID
 30
 31# GA Tracking ID
 32#googleAnalytics:  # Google Analytics 跟踪 ID（已注释，未启用）
 33
 34# Theme i18n support
 35DefaultContentLanguage: zh-cn  # 默认内容语言，设置为中文（简体）
 36
 37# Set hasCJKLanguage to true if DefaultContentLanguage is in [zh-cn ja ko]
 38hasCJKLanguage: true  # 启用 CJK（中文、日文、韩文）语言支持，用于正确分词
 39
 40relativeurls: true          # 启用相对 URL，所有链接将基于当前页面路径生成，而不是绝对路径
 41canonifyurls: false         # 禁用 URL 规范化，保持原始 URL 不被转换为绝对路径
 42uglyurls: false             # 禁用“丑陋 URL”，生成的链接将使用更友好的格式（无 .html 后缀等）
 43
 44permalinks:                 # 定义永久链接（URL）的结构
 45  page:                     # 针对单个页面的 URL 配置
 46    home: /posts/:year/:month/:slug/        # 主页文章的链接格式，例如 /posts/2025/03/my-post/
 47    post: /posts/:year/:month/:slug/        # 博客文章的链接格式，例如 /posts/2025/03/my-post/
 48    about: /about/:slug/                    # 关于页面的链接格式，例如 /about/introduction/
 49    article: /articles/:year/:month/:slug/  # 文章页面的链接格式，例如 /articles/2025/03/my-article/
 50    categories: /categories/:year/:month/:slug/  # 分类页面的链接格式，例如 /categories/2025/03/tech/
 51    doc: /docs/:year/:month/:slug/          # 文档页面的链接格式，例如 /docs/2025/03/guide/
 52    search: /search                         # 搜索页面的固定链接，例如 /search
 53  section:                  # 针对页面类型的整体部分的 URL 配置
 54    home: /posts/           # 主页部分的链接，例如 /posts/
 55    posts: /posts/          # 博客部分的链接，例如 /posts/
 56    about: /about/          # 关于部分的链接，例如 /about/
 57    article: /articles/     # 文章部分的链接，例如 /articles/
 58    categories: /categories/ # 分类部分的链接，例如 /categories/
 59    about: /docs/           # 注意：这里与上面的 about 重复，可能应改为 docs，文档部分的链接，例如 /docs/
 60    search: /search/        # 搜索部分的链接，例如 /search/
 61  term:                     # 针对分类术语（如标签）的 URL 配置
 62    tags: /tags/:year/:month/:slug/         # 标签的链接格式，例如 /tags/2025/03/tech/
 63
 64outputs:  # 输出格式配置
 65    home: ["HTML", "RSS", "JSON"]  # 首页生成 HTML、RSS 和 JSON 文件
 66    section: ["HTML"]  # 分类页面只生成 HTML 文件
 67    page: ["HTML"]  # 单页只生成 HTML 文件
 68
 69outputFormats:  # 自定义输出格式
 70    RSS:  # RSS 格式定义
 71        mediatype: "application/rss+xml"  # RSS 的 MIME 类型
 72        baseName: "rss"  # RSS 文件的基本名称，生成如 rss.xml
 73    JSON:  # JSON 格式定义
 74        mediatype: "application/json"  # JSON 的 MIME 类型
 75        baseName: "index"  # JSON 文件的基本名称，生成如 index.json
 76        isPlainText: true  # JSON 文件以纯文本形式输出
 77
 78services:  # 服务配置
 79    rss:  # RSS 服务设置
 80        limit: 10  # RSS 输出的文章数量限制
 81
 82params:  # 主题参数配置
 83    featuredImageField: image  # 文章特色图片的字段名
 84    rssFullContent: true  # RSS 输出完整文章内容而非摘要
 85    favicon: /img/avatar.png  # 网站图标（favicon）路径
 86
 87    sidebar:  # 侧边栏设置
 88        subtitle: 博观约取 厚积薄发  # 侧边栏副标题
 89        avatar:  # 头像配置
 90            enabled: true  # 启用头像显示
 91            local: true  # 使用本地头像文件
 92            src: /img/avatar.png  # 头像图片路径
 93
 94    mainSections:  # 主内容分区
 95        - post  # 将 "post" 设为主分区，用于首页展示
 96
 97    footer:  # 页脚设置
 98        since: 2025  # 网站起始年份
 99        #customText: ZhuYJ  # 自定义页脚文本（已注释）
100
101    dateFormat:  # 日期格式
102        published: Jan 02, 2006  # 发布日期格式
103        lastUpdated: Jan 02, 2006 15:04 MST  # 最后更新日期格式
104
105    article:  # 文章页面设置
106        math: false  # 是否启用数学公式支持
107        toc: true  # 启用目录（Table of Contents）
108        readingTime: true  # 显示阅读时间
109        license:  # 文章许可声明
110            enabled: false  # 是否启用许可声明
111            default: Licensed under CC BY-NC-SA 4.0  # 默认许可文本（已注释）
112
113    comments: # 评论系统配置
114        enabled: true  # 启用评论功能
115        provider: waline  # 使用 Waline 作为评论提供者
116        disqusjs:  # DisqusJS 配置（未启用）
117            shortname:  # DisqusJS 短名称
118            apiUrl:  # DisqusJS API URL
119            apiKey:  # DisqusJS API 密钥
120            admin:  # 管理员标识
121            adminLabel:  # 管理员标签
122        waline:  # Waline 配置
123            serverURL: https://waline.blain.top/  # Waline 服务器地址
124            lang: zh-cn  # 评论语言，中文
125            pageview: true  # 启用页面浏览量统计
126            emoji:  # 表情包配置 
127                - https://cdn.jsdelivr.net/gh/walinejs/emojis/weibo  # 表情包路径
128            requiredMeta:  # 必填字段
129                - name  # 姓名
130                - email  # 邮箱
131            locale:  # 本地化设置
132                admin: 博主  # 管理员名称
133                placeholder: 🎉留下你的脚印.  # 输入框占位符
134
135#    social:  # 社交媒体链接（已注释） 博主没用这个，根据需求打开
136#        - identifier: github  # 社交媒体标识符
137#          name: GitHub  # 显示名称
138#          url: https://github.com/CaiJimmy/hugo-theme-stack  # 链接地址
139#          params:  # 参数
140#              icon: github  # 图标名称
141#
142#        - identifier: bilibili  # 社交媒体标识符
143#          name: Bilibili  # 显示名称
144#          url: https://space.bilibili.com/450940909  # 链接地址
145#          params:  # 参数
146#              icon: bilibili  # 图标名称
147
148    widgets: # 右侧小部件配置
149        homepage:  # 首页小部件
150            - type: search  # 搜索小部件
151            - type: archives  # 归档小部件
152              params:  # 参数
153                  limit: 5  # 显示条目限制
154            - type: categories  # 分类小部件
155              params:  # 参数
156                  limit: 10  # 显示条目限制
157            - type: tag-cloud  # 标签云小部件
158              params:  # 参数
159                  limit: 10  # 显示条目限制
160        page:  # 单页小部件
161            - type: toc  # 目录小部件
162
163    defaultImage:  # 默认图片设置
164        opengraph:  # Open Graph 默认图片
165            enabled: false  # 是否启用
166            local: false  # 是否使用本地文件
167            src:  # 图片路径
168
169    colorScheme:  # 颜色主题设置
170        toggle: true  # 显示主题切换按钮
171        default: auto  # 默认主题（auto、light、dark）
172
173    imageProcessing:  # 图片处理设置
174        cover:  # 封面图片处理
175            enabled: true  # 启用处理
176        content:  # 内容图片处理
177            enabled: true  # 启用处理
178
179menu:  # 自定义菜单
180    main:  # 主菜单   下面定义了主页/关于/文章收藏/文档收藏/分类/搜索/rss 7个子页面属性
181        - identifier: home  # 菜单项标识符
182          name: 主页  # 显示名称
183          url: /post  # 链接地址
184          weight: -100  # 排序权重，越小越靠前
185          params:  # 参数
186              newTab: false  # 是否在新标签页打开
187              icon: home  # 图标名称
188
189        - identifier: about  # 菜单项标识符
190          name: 关于博主  # 显示名称
191          url: /about  # 链接地址
192          weight: -90  # 排序权重
193          params:  # 参数
194              newTab: false  # 是否在新标签页打开
195              icon: about  # 图标名称
196
197        - identifier: article  # 菜单项标识符
198          name: 文章收藏  # 显示名称
199          url: /articles  # 链接地址
200          weight: -80  # 排序权重
201          params:  # 参数
202              newTab: false  # 是否在新标签页打开
203              icon: article  # 图标名称
204
205        - identifier: doc  # 菜单项标识符
206          name: 文档收藏  # 显示名称
207          url: /doc/  # 链接地址
208          weight: -70  # 排序权重
209          params:  # 参数
210              newTab: false  # 是否在新标签页打开
211              icon: doc  # 图标名称
212
213        - identifier: categories  # 菜单项标识符
214          name: 分类  # 显示名称
215          url: /categories/  # 链接地址
216          weight: -60  # 排序权重
217          params:  # 参数
218              newTab: false  # 是否在新标签页打开
219              icon: categories  # 图标名称
220
221        - identifier: search  # 菜单项标识符
222          name: 搜索  # 显示名称
223          url: /search/  # 链接地址
224          weight: -50  # 排序权重
225          params:  # 参数
226              newTab: false  # 是否在新标签页打开
227              icon: search  # 图标名称
228
229        - identifier: rss  # 菜单项标识符
230          name: rss  # 显示名称
231          url: /rss.xml  # 链接地址
232          weight: -40  # 排序权重
233          params:  # 参数
234              newTab: true  # 在新标签页打开
235              icon: rss  # 图标名称
236
237related:  # 相关文章设置
238    includeNewer: true  # 包括较新的文章
239    threshold: 60  # 相关性阈值
240    toLower: false  # 是否转换为小写
241    indices:  # 相关性索引
242        - name: tags  # 标签索引
243          weight: 100  # 权重
244        - name: categories  # 分类索引
245          weight: 200  # 权重
246
247markup:  # 标记渲染设置
248    goldmark:  # Goldmark 渲染器配置
249        renderer:  # 渲染选项
250            unsafe: true  # 允许不安全的 HTML
251    tableOfContents:  # 目录设置
252        endLevel: 4  # 目录结束级别
253        ordered: true  # 是否有序
254        startLevel: 1  # 目录起始级别
255    highlight:  # 代码高亮设置
256        noClasses: false  # 是否禁用 CSS 类
257        codeFences: true  # 启用代码块
258        guessSyntax: true  # 猜测语法
259        lineNoStart: 1  # 行号起始值
260        lineNos: true  # 显示行号
261        lineNumbersInTable: false  # 行号是否在表格中
262        tabWidth: 4  # 制表符宽度

Add theme (taking the stack theme as an example):

1git init
2git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack
3echo 'theme = "hugo-theme-stack"' >> hugo.yaml

Create a test article:

1hugo new content/posts/test-post.md

Edit ‘content/posts/test-post.md’, change ‘draft: true’ to ‘draft: false’, otherwise restarting the Hugo server will not update the current article;

Start the local server:

1hugo server

Visit ‘http://localhost:1313’ in your browser and you’ll see your blog.

Interface beautification part reference: https://www.tomlife.top/docs/2025/03/hugo-doc/
Waline comment area self-built reference: https://www.tomlife.top/posts/2025/03/hugo-build-waline/

Reference to common Hugo commands

If you need to modify the port, or the link does not use the port, you can check hugo server –help help or leave a message blogger.

Command	Description	Example usage
`hugo`	Generate a static site and output to the public/directory	`hugo --minify`
`hugo server`	Start the development server, default port 1313, real-time preview site	`hugo server --bind 0.0.0.0`
`hugo new`	Create a new content file, such as an article or page `hugo new post/my-post.md`
`hugo version`	Displays the current Hugo version information	`hugo version`
`hugo mod`	Manage Hugo Modules (modular themes or dependencies)	`hugo mod init github.com/user/repo`
`hugo config`	Displays the current configuration information	`hugo config`
`hugo env`	Displays Hugo environment information (e.g., version, Go version)	`hugo env`
`hugo list`	List content files (e.g., drafts, future articles)	`hugo list drafts`
`hugo check`	Check the integrity of the content file	`hugo check`
`hugo --help`	Displays Hugo command help	`hugo --help`

Hugo Build Records

HUGO Blog Build UBUNTU