Hugo 内容文档的原型

简介

Hugo 中存在文档原型(archetypes)的概念,文档原型用来定义内容类型关联的元数据,是文档创作的起点。不同内容类型的文档往往会有不同的 Front Matter 文档头,而不同内容类型又会由不同文档原型来定义相应的文档头。有了文档原型的支持,简化了内容文档的创建,确保了相同内容类型的文档具有一致的文档头。简单来说,文档原型是用来为特定内容类型的文档,预先定义文档头的。

创建原型

Front Matter

TOML YAML格式

结尾空行

样例

原型推断

内置原型

默认原型

类型原型

,要理解什么是文档原型,先来看我们是如何创建内容文档的,使用命令 hugo new post/first-article.md 创建了新的内容文档,而且该文档包含一个头部,用来描述关于文档的一些信息,比如: titledate 等,这样可以省去我们自己定义头部的麻烦。那么使用该命令创建内容文档时,Hugo 又是怎样决定应该为新文档添加哪些头部信息呢,又或者能不能添加不同于默认头部信息的元数据到新建的文档中呢?

这就涉及到了原型的概念,可以认为每个新建的内容文档都来自于一个模板文档,这个预先规定了头部信息的模板文档就是所谓的原型,当我们安装了 Hugo 之后使用 hugo new path/to/content 命令新建的文档是依照 Hugo 内置的默认原型来创建的,因为这个内置原型预定义了 titledate 以及 draft 头部信息,所以我们新建的文档会含有这些头部信息。文档原型和内容文档类型的概念是一一对应的,可以认为属于某个原型的内容文档是同一类型的。

除了使用 Hugo 内置的原型外,Hugo 还支持用户自定义原型。这就是目录 archetypes 的用途,该目录下用来存放用户自定义的各种原型文档。

下面演示如何创建以及使用文档原型

  1. 创建原型文档

    在目录 archetypes 下创建文件 post.md ,并在文件中添加以下内容

    +++
    tags = [""]
    categories = [""]
    +++
    

    注:这里使用了 TOML 格式定义元数据,可以通过修改网站配置文件中的 MetaDataFormat ,来设置网站全局的元数据格式(可选格式有:tomlyaml 以及 json)。

  2. 使用原型来创建内容文档

    hugo new post/my-new-post.md
    

    可以看到新创建的内容文档头部除了 Hugo 内置的 titledate 外,还有 tagscategories 元数据。

  3. 原型的选取

    在运行新建内容文档的命令 hugo new path/to/content.md 时,Hugo 是如何决定该使用哪个原型的呢?Hugo 会根据新建内容文档的路径,来判断文档类型,然后使用相应的原型来创建该文档,比如:路径 post/my-first-post.md 会被识别为 post 类型的文档,相应的会使用 archetypes/post.md 来作为 该文档的原型。如果没有找到相应的原型,就会使用 archetypes/default.md 来作为原型,如果该原型也找不到就使用 Hugo 内置的原型。除了让 Hugo 根据路径来判断文档类型外,还可以在创建内容文档时,通过 --kind 来指定文档的类型。

    除了使用自定义的原型外,还可以使用主题中定义的原型,不过要使用主题原型来创建文档,必须事先在网站配置文件中将网站主题指定为该主题。

内容类型

不同内容类型的文档会使用不同的元数据和模板文件。Hugo 支持用户自定义内容类型并提供了命令 hugo new 来创建特定内容类型的文档。

让我们更进一步来看到底什么是内容类型或者说到底为什么内容要区分类型?我们在生活中每天可以接触到很多很多电子化的内容,比如:朋友圈、微博、个人博客、微视频等,这些显然是不同的内容,需要用不一样的元数据来描述这些内容,像个人博客可能会用标题、作者、日期等元数据来描述一篇博客,而微视频则可能还要指定视频时间长度以及尺寸信息,并且博客跟视频的展现方式肯定是不同的,需要使用不同的模板来展示它们,这样来看 Hugo 允许用户为网站定义多种内容类型就合情合理了。

Hugo 是如何决定一个内容文档的类型呢?在 Hugo 中我们将内容目录中的子目录称为 Section,默认情况下位于某个 Section 下的所有内容文档具有同一内容类型,且内容类型跟所在 Section 同名。并且 Hugo 还提供了用来创建特定类型文档的命令,hugo new post/first-post.md 命令创建的文档位于content/post 目录且文档的内容类型为 post ,打开新建的文档可以看到 Hugo 已经自动为文档添加了相应的头部内容。此外 Section 和 内容类型的这种默认关联可以通过在内容文档头部指定 type 来改变,使用 type 可以显式的为当前文档指定内容类型。

内容类型又是怎样定义的呢?之前有提到每个内容类型都有特定的元数据和模板文件,因此要创建新的内容类型本质上就是定义新的元数据以及创建新的模板文件,假设我们要定义名称为 post 的内容类型,具体来说需要做以下几件事情

  • 创建文档原型

    在文档原型定义目录 archetypes 中创建文件 post.md ,该文件头部指定的元数据就是内容类型 post 的元数据。

  • 创建单页模板

    首先需要在 layouts 目录下创建 post 以存放相应内容类型的模板文件,然后创建 layouts/post/single.html 模板文件,用来定义该内容类型的单页显示方式。

  • 创建列表模板

    创建 layouts/post/list.html 模板文件,用来定义 post 内容类型的列表显示方式。

  • 创建其它模板

    Hugo 不限制内容的呈现方式,除了常见的单页以及列表外,用户可以在模板目录中创建任何模板来自定义内容的显示方式

如果你觉得创建一个内容类型太麻烦了。没关系,上面为内容类型创建文档原型以及各种模板文件都不是必须的,没有创建这些东西,照样可以从逻辑上把内容区分为各种类型,而且同内容类型关联的文档原型以及模板文件都是支持回退的,即找不到对应内容类型的原型以及模板文件时,Hugo 会自动使用默认原型和模板文件。

Previous
Next