>·圍笑就是山貓貓·<

Hugo 常用指令与 Markdown 配置指南

tags: README
@Minjie 2025/12/06
该文章大约 1800 字,预计 4 分钟内读完

详细介绍 Hugo 常用指令、Markdown Front Matter 配置、基本语法和实用技巧的完整指南

摘抄自 Minjie’s Blog, 学习自用,未授权搬运致歉。

一、Hugo 常用指令

1.1 创建新站点

# 创建一个新的 Hugo 站点
hugo new site mysite

# 进入站点目录
cd mysite

1.2 创建新文章

# 在 content/posts 目录下创建新文章
hugo new posts/my-first-post.md

# 在 content 目录下创建文章
hugo new about.md

# 创建在特定子目录
hugo new blog/2024/new-post.md

1.3 本地预览

# 启动本地开发服务器(默认 http://localhost:1313)
hugo server

# 启动并显示草稿文章
hugo server -D

# 启动并显示草稿、未来日期和过期的文章
hugo server -DEF

# 指定端口
hugo server --port 8080

# 实时重载并打开浏览器
hugo server -D --navigateToChanged

1.4 主题管理

# 添加主题(使用 Git submodule)
git submodule add https://github.com/username/theme-name.git themes/theme-name

# 更新主题
git submodule update --remote --merge

# 删除主题
git submodule deinit -f themes/theme-name
rm -rf .git/modules/themes/theme-name
git rm -f themes/theme-name

1.5 其他常用指令

# 查看 Hugo 版本
hugo version

# 查看帮助
hugo help

# 查看配置信息
hugo config

# 列出所有内容
hugo list all

# 列出草稿
hugo list drafts

二、Markdown Front Matter 配置

2.1 完整配置示例

---
# 基本信息
title: "我的第一篇文章"
date: 2025-12-06T15:04:05+08:00
lastmod: 2025-12-07T10:00:00+08:00
draft: false

# 作者信息
author: "Minjie"
authorLink: "https://github.com/Minjie2003"

# 分类和标签
categories: ["技术"]
tags: ["Hugo", "Markdown", "博客"]
series: ["Hugo教程"]

# 摘要和描述
summary: "这是一篇关于 Hugo 和 Markdown 的完整指南"
description: "详细介绍 Hugo 的使用方法和 Markdown 配置"

# 特色图片
image: "/images/featured.jpg"
cover:
    image: "/images/cover.jpg"
    alt: "封面图片描述"
    caption: "图片说明文字"

# SEO 相关
keywords: ["Hugo", "静态博客", "Markdown"]
slug: "hugo-markdown-guide"
url: "/posts/hugo-guide/"

# 显示控制
toc: true                    # 显示目录
comments: true               # 允许评论
showToc: true               # 显示目录
TocOpen: false              # 默认展开目录
hidemeta: false             # 隐藏元信息
disableShare: false         # 禁用分享按钮
hideSummary: false          # 隐藏摘要
ShowReadingTime: true       # 显示阅读时间
ShowBreadCrumbs: true       # 显示面包屑导航
ShowPostNavLinks: true      # 显示文章导航链接

# 权重(用于排序)
weight: 1

# 外部链接
externalLink: "https://example.com"

# 是否在首页显示
showhome: true
---

2.2 常用字段说明

字段 说明 示例
title 文章标题 "我的文章"
date 发布日期 2025-12-062025-12-06T15:04:05+08:00
draft 是否为草稿 true / false
tags 标签(数组) ["Hugo", "博客"]
categories 分类(数组) ["技术", "教程"]
summary 文章摘要 "这是摘要"
description SEO 描述 "页面描述"
slug URL 友好名称 "my-post"
url 自定义完整 URL "/posts/my-post/"
weight 排序权重 1 (数字越小越靠前)
toc 是否显示目录 true / false

三、Hugo.yaml

3.1 完整配置示例

baseURL: "https://example.com/"
languageCode: "zh-cn"
title: "Minjie Blog"
theme: "PaperMod"

# 默认内容语言
defaultContentLanguage: "zh-cn"

#排除某些文件夹
ignoreFiles:
  - "content/obsidian/.*"

# 分页设置
pagination:
  pagerSize: 10

# 构建配置
buildDrafts: false
buildFuture: false
buildExpired: false

# URL 设置
permalinks:
  posts: "/posts/:slug/"

# Markdown 渲染设置
markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:
    style: "monokai"
    lineNos: true

# 站点参数
params:
  author: "Minjie"
  description: "Minjie 的技术博客"
  keywords: ["Hugo", "技术博客", "编程"]

  # 主题相关
  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true

  # 首页信息
  homeInfoParams:
    Title: "欢迎来到 Minjie Blog"
    Content: "记录编程学习和技术成长"

# 菜单配置
menu:
  main:
    - identifier: home
      name: 首页
      url: /
      weight: 1

    - identifier: posts
      name: 文章
      url: /posts/
      weight: 2

    - identifier: categories
      name: 分类
      url: /categories/
      weight: 3

    - identifier: tags
      name: 标签
      url: /tags/
      weight: 4

# 分类和标签
taxonomies:
  category: categories
  tag: tags
  series: series

3.2 常用字段说明

字段 说明 示例
baseURL 网站基础 URL "https://example.com/"
languageCode 网站语言 "zh-cn"
title 网站标题 "Minjie Blog"
theme 使用的主题 "PaperMod"
pagination.pagerSize 每页文章数量 10
permalinks URL 结构规则 "/posts/:slug/"
markup Markdown 渲染配置 代码高亮、HTML支持
params 主题参数配置 作者、描述、UI设置
menu 网站导航菜单 首页 / 文章 / 标签

四、Markdown 基本语法

4.1 标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

4.2 文本样式

**粗体文字**
*斜体文字*
***粗斜体***
~~删除线~~
`行内代码`

4.3 列表

# 无序列表
- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2

# 有序列表
1. 第一项
2. 第二项
   1. 子项 2.1
   2. 子项 2.2

4.4 链接和图片

# 链接
[链接文字](https://example.com)
[带标题的链接](https://example.com "鼠标悬停显示")

# 图片
![图片描述](/images/photo.jpg)
![图片](https://example.com/image.jpg "图片标题")

4.5 引用

> 这是一段引用文字
> 可以多行
>> 嵌套引用

4.6 代码块

```python
def hello():
    print("Hello, Hugo!")
```

```javascript
console.log("Hello, World!");
```

4.7 表格

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |

# 对齐方式
| 左对齐 | 居中 | 右对齐 |
|:-------|:----:|-------:|
| 内容   | 内容 | 内容   |

4.8 分隔线

---
***
___

4.9 任务列表

- [x] 已完成的任务
- [ ] 未完成的任务
- [ ] 另一个任务

五、实用技巧

5.1 文章模板

archetypes/default.md 创建默认模板:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
tags: []
categories: []
summary: ""
---

## 简介

内容开始...

5.2 多语言配置

在 Front Matter 中:

---
title: "English Title"
title.zh: "中文标题"
---

5.3 自定义 URL 结构

hugo.toml 中:

[permalinks]
  posts = "/:year/:month/:slug/"

5.4 草稿快速发布

# 将草稿改为发布状态
sed -i 's/draft: true/draft: false/' content/posts/my-post.md