目录结构

理解 Hugo 的目录结构是使用 Hugo 的基础。本章将详细介绍 Hugo 项目中各个目录和文件的作用。

基本目录结构

使用 hugo new site 命令创建的站点具有以下目录结构：

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

每个目录都有特定的用途，下面逐一介绍。

根目录配置文件

Hugo 的配置文件可以放在根目录，支持三种格式：

hugo.toml（推荐）

TOML 格式，是 Hugo 的默认配置格式：

baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的博客'
theme = 'ananke'

hugo.yaml

YAML 格式，语法更简洁：

baseURL: https://example.org/
languageCode: zh-cn
title: 我的博客
theme: ananke

config.toml / config.yaml / config.json

旧版本的配置文件位置，仍然支持但不推荐。

archetypes 目录

Archetypes 是内容模板，当你使用 hugo new 创建新内容时，Hugo 会根据 archetype 文件生成默认内容。

默认 archetype

archetypes/default.md 是默认模板：

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

自定义 archetype

可以为不同类型的内容创建不同的 archetype。例如，为博客文章创建 archetypes/posts.md：

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

## 前言

## 正文

## 总结

然后创建文章时会自动使用这个模板：

hugo new posts/my-article.md

content 目录

Content 目录是存放网站内容的地方，所有 Markdown 文件都放在这里。Hugo 会根据目录结构自动生成 URL。

基本结构

content/
├── posts/
│   ├── first-post.md
│   └── second-post.md
├── about.md
└── _index.md

URL 生成规则

文件路径	生成的 URL
`content/posts/hello.md`	`/posts/hello/`
`content/posts/hello/index.md`	`/posts/hello/`
`content/about.md`	`/about/`
`content/_index.md`	`/`（首页）

_index.md 文件

_index.md 是列表页面的内容文件。例如 content/posts/_index.md 可以定义博客列表页的标题和描述：

---
title: "博客文章"
description: "我的技术博客文章列表"
---

欢迎阅读我的博客文章！

叶子页面和分支页面

叶子页面（Leaf Bundle）：以 index.md 结尾的内容，如 content/posts/hello/index.md
分支页面（Branch Bundle）：包含 _index.md 的目录，用于列表页

页面资源

与页面相关的资源文件（图片、文件等）可以放在页面目录中：

content/
└── posts/
    └── my-post/
        ├── index.md
        ├── cover.jpg
        └── images/
            └── screenshot.png

在 Markdown 中引用：

![封面图](cover.jpg)
![截图](images/screenshot.png)

layouts 目录

Layouts 目录存放模板文件，用于定义页面的 HTML 结构。

模板查找顺序

Hugo 会按照特定顺序查找模板：

layouts/ 目录
themes/<theme>/layouts/ 目录

常用模板文件

layouts/
├── _default/
│   ├── baseof.html      # 基础模板
│   ├── list.html        # 列表页模板
│   ├── single.html      # 单页模板
│   └── section.html     # 分区模板
├── partials/
│   ├── header.html      # 页头
│   ├── footer.html      # 页脚
│   └── nav.html         # 导航
├── shortcodes/
│   └── youtube.html     # 短代码
└── index.html           # 首页模板

模板继承

baseof.html 是基础模板，其他模板可以继承它：

<!-- layouts/_default/baseof.html -->
<!DOCTYPE html>
<html>
<head>
    <title>{{ .Title }} | {{ .Site.Title }}</title>
</head>
<body>
    {{ block "main" . }}{{ end }}
</body>
</html>

<!-- layouts/_default/single.html -->
{{ define "main" }}
<article>
    <h1>{{ .Title }}</h1>
    {{ .Content }}
</article>
{{ end }}

static 目录

Static 目录存放静态文件，构建时会直接复制到输出目录。

static/
├── images/
│   └── logo.png
├── css/
│   └── custom.css
├── js/
│   └── main.js
└── files/
    └── resume.pdf

访问方式：/images/logo.png、/css/custom.css

注意：Hugo 0.78 版本后推荐使用 assets/ 目录处理需要处理的资源，static/ 仅用于不需要处理的静态文件。

assets 目录

Assets 目录存放需要 Hugo 管理的资源文件，如 CSS、JavaScript、图片等。

与 static 目录的区别

特性	assets	static
资源处理	支持（压缩、指纹等）	直接复制
图片处理	支持（调整大小、格式转换）	不支持
Sass/SCSS	支持	不支持
访问方式	通过 `.Resources.Get`	直接 URL 访问

使用示例

<!-- 在模板中引用 -->
{{ $style := resources.Get "css/main.css" | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

data 目录

Data 目录存放数据文件，支持 TOML、YAML、JSON 格式。可以在模板中读取这些数据。

示例：作者信息

data/authors.toml：

[alice]
  name = "Alice"
  bio = "前端开发工程师"
  avatar = "/images/avatar-alice.jpg"

[bob]
  name = "Bob"
  bio = "后端开发工程师"
  avatar = "/images/avatar-bob.jpg"

在模板中使用：

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

themes 目录

Themes 目录存放主题文件。每个主题是一个独立的子目录，包含自己的 layouts、static、assets 等。

安装主题

# 作为 Git 子模块安装
git submodule add https://github.com/user/theme-name.git themes/theme-name

# 或者直接克隆
git clone https://github.com/user/theme-name.git themes/theme-name

启用主题

在 hugo.toml 中配置：

theme = 'theme-name'

主题目录结构

themes/
└── theme-name/
    ├── layouts/
    ├── static/
    ├── assets/
    ├── archetypes/
    └── theme.toml    # 主题配置

public 目录

Public 目录是构建输出目录，运行 hugo 命令后生成的静态文件都在这里。

public/
├── index.html
├── posts/
│   ├── first-post/
│   │   └── index.html
│   └── index.html
├── css/
├── js/
└── images/

注意事项

不要手动编辑 public 目录中的文件
可以将 public 目录添加到 .gitignore
部署时只需要上传 public 目录的内容

resources 目录

Resources 目录存放 Hugo 生成的缓存资源，如处理后的图片、编译后的 CSS 等。

这个目录通常不需要手动管理，Hugo 会自动处理。可以将其添加到 .gitignore。

完整目录结构示例

一个完整的 Hugo 项目结构可能如下：

myblog/
├── archetypes/
│   ├── default.md
│   └── posts.md
├── assets/
│   ├── css/
│   │   └── main.css
│   └── js/
│       └── main.js
├── content/
│   ├── posts/
│   │   ├── _index.md
│   │   ├── first-post.md
│   │   └── second-post/
│   │       ├── index.md
│   │       └── cover.jpg
│   ├── about.md
│   └── _index.md
├── data/
│   └── links.toml
├── layouts/
│   ├── _default/
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── partials/
│   │   ├── header.html
│   │   └── footer.html
│   └── index.html
├── static/
│   └── images/
│       └── favicon.ico
├── themes/
│   └── ananke/
├── hugo.toml
└── .gitignore

配置目录位置

可以通过配置修改默认目录位置：

# hugo.toml
contentDir = "content"
layoutDir = "layouts"
staticDir = "static"
assetDir = "assets"
dataDir = "data"
themesDir = "themes"
archetypeDir = "archetypes"
publishDir = "public"
resourceDir = "resources"

小结

本章介绍了 Hugo 的目录结构，关键要点：

content/ 存放内容文件，目录结构决定 URL 结构
layouts/ 存放模板文件，控制页面 HTML 结构
static/ 存放静态文件，直接复制到输出目录
assets/ 存放需要处理的资源文件
archetypes/ 定义新内容的默认模板
themes/ 存放主题文件

理解目录结构是使用 Hugo 的基础，下一章将学习内容管理的详细知识。

基本目录结构​

根目录配置文件​

archetypes 目录​

content 目录​

layouts 目录​

static 目录​

assets 目录​

data 目录​

themes 目录​

public 目录​

resources 目录​

完整目录结构示例​

配置目录位置​

小结​