01_撰写第一篇文章

发表于：
字数： 3026 阅读：≈ 7分钟 浏览：
总结摘要
安装 Hugo 并撰写第一篇文章，了解 Hugo 的目录结构，配置博客雏形文件，添加图片引用来正确显示图片。

安装 Hugo

为了实现本地和服务器上同时查看博客网站的内容需要在本地和服务器上分别安装 Hugo 软件，作者本地计算机的操作系统为 Windows 11 22H2，服务器的操作系统为Ubuntu 22.04.5 LTS。

本地安装 Hugo

在 Windows 安装 Hugo 可以参考官方的[安装教程]( Windows | Hugo官方文档 )，采用包管理器的方式安装 Hugo。Windows 11上已经预先安装 Winget 包管理器，安装 Hugo 的命令如下：

1

winget install Hugo.Hugo.Extended

但是在我的电脑上安装时却提示下面的错误，在网上冲浪半天也没有找到合适的解决方案。

1
2
3
4
5
6

PS C:\Users\Sun> winget install Hugo.Hugo.Extended
已找到 Hugo(扩展版) [Hugo.Hugo.Extended] 版本 0.147.7
此应用程序由其所有者授权给你。
Microsoft 对第三方程序包概不负责，也不向第三方程序包授予任何许可证。
执行此命令时发生意外错误：
0x80070032 : ��֧�ָ�����

索性直接到 Github 的 [Hugo 发布页面]( Releases · gohugoio/hugo )上下载安装最近的安装包。根据需要，我安装的是Hugo的扩展版 hugo_extended_0.147.7_windows-amd64.zip ，下载完成后解压文件，并将解压后的文件夹添加到环境变量中，以便后续通过命令行执行 Hugo 命令。

在命令行中执行 Hugo version 来检查 Hugo 是否安装成功，成功安装后将显示下面的内容。

1

hugo v0.147.7-189453612e4bedc4f27495a7b1145321c8d89807+extended windows/amd64 BuildDate=2025-05-31T12:41:12Z VendorInfo=gohugoio

安装完 Hugo 后，需要安装 Git for Windows 来与服务器进行版本同步和安装 Hugo 主题，安装 Git for Windows 时一路点击下一步即可。

建立 Hugo 网站

选择一个文件夹，执行下面的命令来创建 Hugo 网站。

1
2

# 建立 Hugo 网站，HugoBlogs 为网站文件夹名称。
hugo new site HugoBlogs

命令执行完成后将在指定的文件夹内创建 HugoBlogs 文件夹， HugoBlogs 文件夹内的结构如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

HugoBlogs/
├── archetypes/
│   └── default.md
├── assets/
├── content/
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml         <-- 站点配置

存在多个配置文件时，可将站点配置文件放到 config 文件夹

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

HugoBlogs/
├── archetypes/
│   └── default.md
├── assets/
├── config/           <-- 站点配置
│   └── _default/
│       └── hugo.toml
├── content/
├── data/
├── i18n/
├── layouts/
├── static/
└── themes/

构建站点时，Hugo 会创建一个 public 目录，通常还会创建一个 resources 目录。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

HugoBlogs/
├── archetypes/
│   └── default.md
├── assets/
├── config/       
│   └── _default/
│       └── hugo.toml
├── content/
├── data/
├── i18n/
├── layouts/
├── public/       <-- 构建站点时创建
├── resources/    <-- 构建站点时创建
├── static/
└── themes/
  • archetypes 目录包含用于新内容的雏形。每次执行 hugo new content xxx/xxx.md 命令时，将根据雏形文件的内容创建md文件。
  • assets 目录包含通常通过资源管道传递的全局资源。包括图片、CSS、Sass、JavaScript 和 TypeScript 等资源。因为在撰写 Markdown 文件时一般将图片资源放在 static 文件夹下，所以不需要太关心 assets 文件夹，除非是在自己制作 Hugo 主题时。
  • config 目录包含站点配置，可分为多个子目录和文件。对于配置较少或不需要在不同环境中以不同方式运行的项目，项目根目录中的单个 hugo.toml 配置文件就足够了。
  • content 目录包含组成站点内容的标记文件（通常是 Markdown）和页面资源。
  • data 目录包含用于增强内容、配置、本地化和导航的数据文件（JSON、TOML、YAML 或 XML）。
  • i18n 目录包含多语言站点的翻译表。
  • layouts 目录包含将内容、数据和资源转换为完整网站的模板。
  • public 目录包含发布的网站，在运行 hugo 命令时生成。Hugo 根据需要重建此目录及其内容。
  • resources 目录包含 Hugo 资源管道的缓存输出，在运行 hugo 或 hugo server 命令时生成。默认情况下，此缓存目录包括 CSS 和图片。Hugo 根据需要重建此目录及其内容。
  • static 目录包含在构建站点时将复制到 public 目录的文件，例如 favicon.ico、robots.txt 和用于验证站点拥有权的文件。在引入 页面包 和 资源管道 之前，static 目录也用于存放图片、CSS 和 JavaScript 等资源。
  • themes 目录包含一个或多个 主题 ，每个主题位于自己的子目录中。

在实际使用时，一般首先在 themes 目录中设置好第三方主题。其次，配置 hugo.toml 文件或者配置 config 目录进行站点参数配置。再次，在 archetypes 目录中配置好相应的雏形文件。最后，开始撰写博客，将 Markdown 文件放到 content 目录下，将图片等文件放到 public 目录下。

配置 Hugo 主题

根据个人爱好选择一个合适的 Hugo Themes 。这里选择的是 hugo-next 主题。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 进入 HugoBlogs 文件夹
cd HugoBlogs
# 初始化一个空的 Git 仓库
git init
# 将 hugo-next 主题克隆到 themes 目录中，并将其作为 Git 子模块添加到项目中
git submodule add https://github.com/hugo-next/hugo-theme-next.git themes/hugo-theme-next
# 将 hugo-next 主题的示例配置文件拷贝到站点的根目录
cp themes/hugo-theme-next/exampleSite/hugo.yaml .
# 修改原本配置文件的后缀名（在站点根目录只能有一个配置文件）
mv hugo.toml hugo.toml.backup

hugo-next 主题支持修改脚注和侧边栏，在编译博客网站前，需要创建脚注和侧边栏的 html 文件。可以将主题的示例 html 文件拷贝到站点目录中，或者根据个人喜好来自定义。

1
2

\themes\hugo-theme-next\exampleSite\layouts\partials\custom_footer.html -> \layouts\partials\custom_footer.html
\themes\hugo-theme-next\exampleSite\layouts\partials\custom_sidebar.html -> \layouts\partials\custom_sidebar.html

启动 Hugo 的开发服务器以查看网站。

1

hugo server -D
错误

如果没有添加 custom_footer.html 和 custom_sidebar.html 这一步将编译失败。

添加第一个博客

接下来创建第一个博客文件，配置雏形文件，并在 typora 中正确设置图片的引用路径。

设置雏形

所有的 Markdown 文件都需要放在网站的 content 目录下，已保证内容的正确显示。可以直接在content 目录新建空白的 .md 文件，或使用 archetypes 目录下的雏形来创建 .md 文件，命令如下：

1

hugo new content/posts/my-first-post.md

Hugo 会使用 archetypes 目录下的 default.md 雏形在 content/posts 目录中创建该文件。default.md 雏形下的默认内容如下：

1
2
3
4
5

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

生成的 my-first-post.md 的内容如下：

1
2
3

date = '2025-06-09T19:16:37+08:00'
draft = true
title = 'My First Post'

Hugo在项目根目录中的 archetypes 目录中查找雏形，如果不存在，则回退到主题或已安装模块中的 archetypes 目录。特定内容类型的雏形优先于默认的雏形。

1
2
3
4

 archetypes/
├── posts.md
├── default.md
└── tutorials.md

例如，使用以下命令：

1

hugo new content posts/my-first-post.md

雏形的查找顺序为：

  1. archetypes/posts.md
  2. archetypes/default.md
  3. themes/my-theme/archetypes/posts.md
  4. themes/my-theme/archetypes/default.md

如果这些都不存在，Hugo 将使用内置的默认雏形。

如果想要指定创建 .md 文件时使用的雏形可以添加 --kind 命令行参数。使用 tutorials 雏形创建文章：

1

hugo new content --kind tutorials posts/my-first-post.md

关于雏形的详细使用方法可以参考官方文档 雏形 | Hugo官方文档 。

参照 hugo-next 的默认雏形，本人采用的默认雏形内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

---
title:  '{{ replace .Name "-" " " | title }}'
date: '{{ .Date }}'
lastmod: '{{ .Date }}'
draft: true

description:  '{{ .Name }}'
keywords:  '{{replace .Name "-" ","}}'

categories:
  -
tags:
  -
  
# 在首页展开内容
#expand: true
# 在当前页面关闭评论功能
#comment:
# enable: false
# 关闭文章目录功能
#toc: false
# 开启文章置顶，数字越小越靠前
#weight: 1
# 开启数学公式渲染，可选值： mathjax, katex
#math: mathjax
# 开启各种图渲染，如流程图、时序图、类图等
#mermaid: true

---

设置图片引用

考虑到图床存在失效的问题，且本人习惯在本地保存数据备份，因此，采用本地保存图片的方案。

Hugo 在编译网站时，会将 static 目录下的所有内容拷贝到网站根目录（ public 目录）下。当图片存放的路径为 static/imgs/1.png 时，引用图片的格式为：

1

![示例图片](/imgs/1.png)

在 Typora 中需要指定图片的根目录才能正确显示 static 目录下的图片内容。在菜单依次选择 格式(O)->图像->设置图片根目录... 子菜单，将弹出文件夹选择对话框，选择站点下 static 目录即可。

上述的操作步骤等同于在 Markdown 文件的头部添加如下内容：

1
2
3

---
typora-root-url: ./..\..\..\..\static
---

如果上面的图片根目录配置正确，图片 static/imgs/fll.png 将在 Typora 和网站中正确显示。

接下来就可以愉快的撰写博客了，当博客撰写完成后使用 hugo server -D 命令对博客进行审查，内容没有问题将文件头部的 draft 参数设置为 false，将博客发布到正式网站中。

1
2
3
4

---
- draft: true
+ draft: false
---

Hugo允许你在内容的 前置元数据 中设置draft、date、publishDate和expiryDate。默认情况下，Hugo在以下情况下不会发布内容：

  • draft的值为true
  • date在未来
  • publishDate在未来
  • expiryDate在过去

你可以在运行hugo或hugo server时使用命令行标志覆盖默认行为：

1
2
3

hugo --buildDrafts    # 或 -D
hugo --buildExpired   # 或 -E
hugo --buildFuture    # 或 -F

尽管你也可以在站点配置中设置这些值，但除非所有内容作者都了解并理解这些设置，否则可能会导致意外结果。

关于 draft 详细用法可参考 基本用法 | Hugo官方文档 中的草稿、未来和过期内容部分。