文件组织 – Hextra

文件组织

目录结构

默认情况下，Hugo 会在 content 目录中查找 Markdown 文件，目录的结构决定了网站最终的输出结构。以本网站为例：

_index.md
- _index.md
- getting-started.md
- - _index.md
  - organize-files.md
- _index.md
- post-1.md

每个 _index.md 文件都是对应部分的索引页。其他 Markdown 文件则是常规页面。

content
├── _index.md // <- /
├── docs
│   ├── _index.md // <- /docs/
│   ├── getting-started.md // <- /docs/getting-started/
│   └── guide
│       ├── _index.md // <- /docs/guide/
│       └── organize-files.md // <- /docs/guide/organize-files/
└── blog
    ├── _index.md // <- /blog/
    └── post-1.md // <- /blog/post-1/

布局

Hextra 为不同类型的内容提供了三种布局：

布局	目录	特点
`docs`	`content/docs/`	适合结构化文档，与本部分相同。
`blog`	`content/blog/`	用于博客文章，包含列表和详细文章视图。
`default`	其他所有目录	单页文章视图，无侧边栏。

要自定义一个部分以模仿内置布局的行为，可以在该部分的 _index.md 的 front matter 中指定所需的类型。

content/my-docs/_index.md

---
title: 我的文档
cascade:
  type: docs
---

上述示例配置确保 content/my-docs/ 内的内容文件默认会被视为文档（docs 类型）。

侧边栏导航

侧边栏导航会根据内容组织按字母顺序自动生成。要手动配置侧边栏顺序，可以在 Markdown 文件的 front matter 中使用 weight 参数。

content/docs/guide/_index.md

---
title: 指南
weight: 2
---

ℹ️

建议不要让侧边栏过深。如果有大量内容，可以考虑将其拆分为多个部分。

部分导航

部分分页顺序

通过 PAGE.PrevInSection 和 PAGE.NextInSection 访问的页面在页面集合中的顺序默认是反向的。

要禁用这种反向排序，可以在页面的 front matter 中将 reversePagination 自定义参数设置为 false。默认情况下，reversePagination 设置为 true。

示例

给定以下目录结构：

_index.md
- _index.md
- - _index.md
  - - index.md
  - - index.md
  - - index.md

并在文章的 front matter 中设置：

content/blog/my-blog-series/post-a/index.md

---
title: 文章 A
weight: 1
---

content/blog/my-blog-series/post-b/index.md

---
title: 文章 B
weight: 2
---

content/blog/my-blog-series/post-c/index.md

---
title: 文章 C
weight: 3
---

如果读者位于 post-b/index.md 的底部，他们会看到下一页是 post-a，上一页是 post-c。这是由于 reversePagination 默认设置为 true。当我们希望文章按从最新到最旧的顺序显示时，这是可以的。然而，对于多部分的博客系列，我们通常希望读者先阅读第一部分，然后依次阅读后续部分。因此，我们希望禁用反向排序。

我们可以通过在 my-blog-series/_index.md 中添加以下 front matter 来关闭该系列中所有博客文章的 reversePagination：

content/blog/my-blog-series/_index.md

---
title: 我的博客系列
cascade:
    params:
        reversePagination: false
---

这里我们使用 cascade 将设置传播到 my-blog-series 中的所有文章，以便所有后代都将 reversePagination 设置为 false。这将确保当读者在 post-b/index.md 时，他们会看到下一页是 post-c，上一页是 post-a。

面包屑导航

面包屑会根据 /content 的目录结构自动生成。

例如，考虑上面展示的文件结构。给定该结构，位于 /docs/guide/organize-files/ 的页面顶部的面包屑会自动显示如下：

文档 > 指南 > 组织文件

自定义面包屑链接标题

默认情况下，每个面包屑链接是根据该页面的 title 参数生成的。可以通过指定 linkTitle 来自定义。

例如，如果我们希望面包屑显示为 Foo Bar 而不是 Organize Files：

content/docs/guide/organize-files.md

---
linkTitle: Foo Bar
title: 组织文件
---

现在会生成以下面包屑：

文档 > 指南 > Foo Bar

隐藏面包屑

可以通过在页面的 front matter 中指定 breadcrumbs: false 来完全隐藏面包屑：

content/docs/guide/organize-files.md

---
breadcrumbs: false
title: 组织文件
---

配置内容目录

默认情况下，Hugo 使用根目录 content/ 来构建网站。如果需要使用其他目录作为内容目录，例如 docs/，可以在站点配置 hugo.yaml 中设置 contentDir 参数。

添加图片

添加图片最简单的方法是将图片文件放在与 Markdown 文件相同的目录中。例如，将图片文件 image.png 与 my-page.md 文件放在一起：

- my-page.md
- image.png

然后，可以使用以下 Markdown 语法将图片添加到内容中：

content/docs/my-page.md

![](image.png)

我们还可以利用 Hugo 的页面包功能将图片文件与 Markdown 文件组织在一起。为此，将 my-page.md 文件转换为目录 my-page，并将内容放入名为 index.md 的文件中，然后将图片文件放入 my-page 目录中：

- - index.md
  - image.png

content/docs/my-page/index.md

![](image.png)

或者，我们也可以将图片文件放在 static 目录中，这样所有页面都可以访问这些图片：

- image.png

- my-page.md

注意，图片路径以斜杠 / 开头，并且相对于 static 目录：

content/docs/my-page.md

![](/images/image.png)

最后更新于 August 14, 2025

指南 Markdown