Hugo 项目文件结构详解

mysite/
├── archetypes/
│   └── default.md
├── assets/
├── content/
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml

baseURL = "https://example.com/"
languageCode = "zh-CN"
title = "我的 Hugo 网站"
theme = "ananke"

[params]
  description = "这是我的个人博客"
  author = "张三"

[menu]
  [[menu.main]]
    name = "首页"
    url = "/"
    weight = 1
  [[menu.main]]
    name = "文章"
    url = "/posts/"
    weight = 2

config/
├── _default/
│   ├── hugo.toml      # 基础配置
│   ├── menus.toml     # 菜单配置
│   └── params.toml    # 自定义参数
├── production/
│   └── hugo.toml      # 生产环境覆盖配置
└── development/
    └── hugo.toml      # 开发环境覆盖配置

content/
├── _index.md          # 网站首页内容
├── posts/
│   ├── _index.md      # posts 列表页内容
│   ├── first-post.md
│   └── second-post.md
├── about.md
└── projects/
    ├── _index.md
    └── my-app.md

---
title: "我的第一篇文章"
date: 2026-03-25T08:00:00+08:00
draft: false
tags: ["Go", "Hugo"]
categories: ["教程"]
slug: "my-first-post"
weight: 1
cover:
  image: "images/cover.jpg"
  alt: "封面图片"
---

正文内容从这里开始...

layouts/
├── _default/
│   ├── baseof.html    # 基础模板（所有页面的骨架）
│   ├── single.html    # 单页面模板（文章详情页）
│   ├── list.html      # 列表页模板（分类、标签、归档）
│   └── summary.html   # 摘要模板
├── partials/
│   ├── header.html    # 页头片段
│   ├── footer.html    # 页脚片段
│   ├── nav.html       # 导航片段
│   └── seo.html       # SEO 元标签片段
├── shortcodes/
│   ├── figure.html    # 图片短代码
│   └── notice.html    # 提示框短代码
├── index.html         # 网站首页模板
└── 404.html           # 404 页面模板

<!DOCTYPE html>
<html lang="{{ .Site.Language.Lang }}">
<head>
  <meta charset="UTF-8">
  <title>{{ block "title" . }}{{ .Site.Title }}{{ end }}</title>
  {{ partial "seo.html" . }}
</head>
<body>
  {{ partial "header.html" . }}
  <main>
    {{ block "main" . }}{{ end }}
  </main>
  {{ partial "footer.html" . }}
</body>
</html>

<!-- 使用内置短代码 -->
{{</* figure src="image.jpg" title="图片标题" */>}}

<!-- 使用自定义短代码 notice.html -->
{{</* notice warning */>}}
这是一条警告信息！
{{</* /notice */>}}

static/
├── images/
│   ├── logo.png
│   └── favicon.ico
├── css/
│   └── custom.css
├── js/
│   └── main.js
└── robots.txt

<img src="/images/logo.png" alt="Logo">
<link rel="stylesheet" href="/css/custom.css">

assets/
├── scss/
│   ├── main.scss
│   └── _variables.scss
├── js/
│   └── app.js
└── images/
    └── hero.jpg

{{ $style := resources.Get "scss/main.scss" | toCSS | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}" integrity="{{ $style.Data.Integrity }}">

archetypes/
├── default.md     # 默认模板
└── posts.md       # posts 目录专用模板

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

## 摘要

在此处写文章摘要...

## 正文

在此处写正文内容...

# 使用 default.md 模板
hugo new posts/my-new-post.md

# 使用指定模板
hugo new --kind posts posts/another-post.md

data/
├── authors.yaml
├── team.json
└── config/
    └── social.toml

- name: 张三
  email: zhangsan@example.com
  bio: "前端工程师，热爱开源"
- name: 李四
  email: lisi@example.com
  bio: "后端开发者，Go 语言爱好者"

{{ range .Site.Data.authors }}
  <div class="author">
    <h3>{{ .name }}</h3>
    <p>{{ .bio }}</p>
  </div>
{{ end }}

i18n/
├── zh-CN.yaml
└── en.yaml

readMore:
  other: 阅读更多
publishedOn:
  other: 发布于
tags:
  other: 标签
home:
  other: 首页

<a href="{{ .Permalink }}">{{ i18n "readMore" }}</a>

themes/
└── ananke/
    ├── archetypes/
    ├── assets/
    ├── layouts/
    ├── static/
    └── theme.toml

# 方式一：Git Submodule（推荐）
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke

# 方式二：Hugo Modules（现代方式）
hugo mod init github.com/yourname/yoursite
# 在 hugo.toml 中配置

public/
├── index.html
├── posts/
│   ├── index.html
│   └── my-post/
│       └── index.html
├── css/
├── js/
└── sitemap.xml

# 创建新站点
hugo new site mysite

# 本地开发服务器（包含草稿）
hugo server -D

# 构建生产版本
hugo

# 创建新内容
hugo new posts/hello-world.md

# 指定输出目录
hugo --destination ./dist

# 查看 Hugo 版本
hugo version

优先级（高 → 低）：
项目 layouts/ > 项目 assets/ > 主题 layouts/ > 主题 assets/