Hugo 目录结构

简介

用 Hugo 创建网站,其实就是生成了一个目录,该目录中又包含一些文件和子目录,内容创作者可以根据自己的需要添加、修改或删除目录和文件。最终在生成网站时,Hugo 会将该目录作为唯一的输入内容,并按照创作者对内容文档的组织意图来生成相应结构的静态网站文件。当然该目录中的子目录和文件的用途都是遵从了 Hugo 的某些约定,更多的了解 Hugo 对这些文件和子目录的用途约定,有利于创作者更好的构建网站。

术语

为了方便阐述和理解本文内容,先来介绍几个术语:

  • 源目录

    用来生成静态网站的唯一数据来源,也即通过网站创建命令来生成的目录。该目录中存放了撰写的文章、网站的配置文件以及所有一切相关数据。

  • 目标目录

    静态网站生成的目录位置,Hugo 默认会将生成的静态网站放置在源目录中的 public 子目录中。

  • 内容文档

    我们把撰写文章的文档称为内容文档,该文档含有用 Markdown 等标记语言书写的文章内容以及一些用来描述文档的头部信息。

  • 文档元数据

    文档头部用来描述文档的信息叫做元数据,元数据一般包含:文章标题、编辑时间以及作者等跟文档相关的信息。这些文档头的元数据通常又被叫做 Front Matter

  • 草稿文档

    草稿文档就是还在撰写,没有完成的文档,默认草稿文档是不会被发布出去的。此外文档头部的发布日期和失效日期也可以控制文档是否被发布。

  • 网站主题

    内容文档仅仅是内容,在转换为静态网站时,通常我们会希望网页具有丰富多样的表现形式,比如是否为网页添加侧边栏、是否进行分页显示以及网站首页要呈现怎样的内容等,关于内容的表现形式统统由主题来控制,而且 Hugo 允许我们使用不同主题来生成不同风格的网站。Hugo 还提供了丰富的主题资源,我们可以直接使用这些主题,还可以扩展它们。

  • 模板文件

    在将内容文档转换为网页的时候,是按照主题或者自定义的某种约定进行转换的,用来约定内容文档如何转换为网页的文件就叫做模板文件,模板文件主要用来定义内容文档是如何填充到网页结构中的,其实可以将模板文件看成是待填充的网页样板。网站主题其实就是由很多静态资源文件(包括:CSS 、Javascript 和图片等)以及模板文件构成的。

新建网站的结构

在运行完网站创建命令 hugo new site mysite 之后,将会得到如下目录结构:

mysitename
 ├─config.toml
 ├─archetypes
 ├─content
 ├─data
 ├─layouts
 ├─static
 └─themes

该目录就是网站的源目录,是生成静态网站的唯一数据来源,其中存放了编辑的文章、网站的配置文件以及所有一切相关数据。所有编辑的文档以及下载的主题文件都存放在该目录下,在生成静态网站内容时,Hugo 会自动根据创作者对该目录的组织规划,来将其转换为相应结构的静态网站。接下来将依次介绍以上目录和文件的用途。

config.toml

Hugo 将网站源目录转换为静态网站的过程,大多情况都符合我们的预期。此外,Hugo 还允许我们通过配置项来控制网站的生成过程。config.toml 正是用来存放这些配置项的,Hugo 在生成静态网站时会读取该配置文件。注意到该文件的后缀名为 toml ,这表明配置内容是 TOML 格式的,此外还可以使用 YAML 和 JSON 格式来创建配置文件。

archetypes

archetypes 目录用来存放文档原型文件,所谓文档原型其实就是预定义了一些文档头部信息。比如 Hugo 使用 hugo new path-to-article.md 新建的内容文档,默认会包含 title , date , draft 这些头部信息。这是由于 Hugo 默认文档原型定义了这些头部信息,除了使用 Hugo 默认文档原型外,我们也可以定义自己的文档原型,然后可以在创建的内容文档中插入自己定义的文档头部信息。

content

content 顾名思义是用来存放内容文档的目录。Hugo 假设我们对该目录的组织是有特定意图的,因此如何组织该目录结构将会直接影响到最终生成的静态网站结构。具体来说 Hugo 会按照该目录的结构来规划网站的目录组织结构,除了内容文档外(内容文档需要被转换为 HTML 文件),其余文件以及目录结构都被原样复制到生成的网站目录中。基于这个原因,该目录下第一级子目录又被叫做 content section,因为它们将直接对应静态网站的顶级内容划分。

data

data 目录用来存放一些数据文件。不同于内容文档,数据文件并不会被转换为网页,而是为内容文档提供数据。当你觉得塞在内容文档头部的信息太多时,可以考虑将其迁移到数据文件中,或者当我们想要在网站展示大量的数据时,也可以考虑将它们存放在该目录下,把数据文件单独放在一起,方便管理。

数据文件可以使用 YAML , JSON , TOML 格式来保存,并且数据目录中的数据会以键值对的形式被保存在模板变量 .Site.Data 中,这样就可以在模板文件中渲染这些数据了。此外 Hugo 的模板文件还支持通过函数 getJSONgetCSV 来加载动态数据,更多内容参见官网

layouts

该目录用来存放模板文件,模板文件决定了内容文档最终将如何呈现在静态网站上。生成静态网站时该目录下的模板文件会替代主题目录中同名模板文件来发挥作用。常见的模板文件类型有:single page, list page, homepage, taxonomy template, partial 等。

static

存放自定义的图片、 CSS 以及 Javascript 等资源文件,在生成网站时该目录中的内容会被原样复制到静态网站目录中,该目录结构如何组织完全取决于自己,一般来说通常会创建 jscssimg 子目录用来存放相应的资源文件。

themes

存放主题文件夹,Hugo 社区提供了丰富的主题资源以供用户选择,我们可以下载喜欢的主题放在该目录下,在生成网站时可以使用下载好的主题。主题资源一般来说会含有模板文件以及相关图片等资源文件。Hugo 支持用户从多个粒度对主题进行自定义,也即可以把主题的部分内容替换为自定义的内容。

Previous
Next