アーキタイプ

概要

コンテントファイルというものはフロントマター (front matter) とマークアップから構成されます。マークアップは一般にはマークダウンのことです。 Hugo ではさらに別のコンテントフォーマットもサポートされます。フロントマターは TOML, YAML, JSON による表現が可能です。

hugo new content コマンドを実行すると、content ディレクトリ下に新たなファイルを生成します。その際にはアーキタイプ (archetype) を使ってテンプレートとして生成します。デフォルトのアーキタイプを以下のように記述したとします。

archetypes/default.md

---
date: '{{ .Date }}'
draft: true
title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
---

+++
date = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+++

{
   "date": "{{ .Date }}",
   "draft": true,
   "title": "{{ replace .File.ContentBaseName `-` ` ` | title }}"
}

新規にコンテントを生成すると、Hugo はアーキタイプ内にあるテンプレートアクションを確認します。

hugo new content posts/my-first-post.md

上で示したようなデフォルトのアーキタイプが用いられた場合、Hugo は以下のようなファイルを生成します。

content/posts/my-first-post.md

---
date: "2023-08-24T11:49:46-07:00"
draft: true
title: My First Post
---

+++
date = '2023-08-24T11:49:46-07:00'
draft = true
title = 'My First Post'
+++

{
   "date": "2023-08-24T11:49:46-07:00",
   "draft": true,
   "title": "My First Post"
}

アーキタイプは 1 つあるいは複数のコンテントタイプに対して作ることができます。たとえば post 生成時には特定のアーキタイプを利用するものとし、それ以外に対してはデフォルトのアーキタイプを利用するといった具合です。

archetypes/
├── default.md
└── posts.md

検索順

Hugo がアーキタイプを探す場所は、プロジェクトのルート配下にある archetypes ディレクトリです。次にテーマあるいはインストールモジュールの archetypes ディレクトリを探します。特定のコンテントタイプに対応するアーキタイプは、デフォルトのアーキタイプよりも優先されます。

たとえば以下のコマンドを実行したとします。

hugo new content posts/my-first-post.md

アーキタイプを検索する順は以下となります。

archetypes/posts.md
archetypes/default.md
themes/my-theme/archetypes/posts.md
themes/my-theme/archetypes/default.md

そのどれもが見つからなかった場合、Hubo はあらかじめ用意しているデフォルトのアーキタイプを用います。

関数とコンテキスト

アーキタイプ内ではテンプレート関数を利用できます。上で示したように、デフォルトのアーキタイプ内では replace 関数を使っていて、そこではフロントマター内のタイトルを生成するにあたり、ハイフンをスペース文字に置換することを行っています。

アーキタイプは以下のコンテキスト (context) を受け取ります。

Date: (string) The current date and time, formatted in compliance with RFC3339.
File: (hugolib.fileInfo) Returns file information for the current page. See details.
Type: (string) The content type inferred from the top-level directory name, or as specified by the --kind flag passed to the hugo new content command.

Site: (page.Site) The current site object. See details.

Alternate date format

To insert date and time with an alternate format, use the time.Now function:

archetypes/default.md

---
date: '{{ time.Now.Format "2006-01-02" }}'
draft: true
title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
---

+++
date = '{{ time.Now.Format "2006-01-02" }}'
draft = true
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+++

{
   "date": "{{ time.Now.Format \"2006-01-02\" }}",
   "draft": true,
   "title": "{{ replace .File.ContentBaseName `-` ` ` | title }}"
}

コンテントを含むアーキタイプ

アーキタイプはフロントマターのテンプレートとして利用するのが普通ですが、これをコンテント生成のために利用することもできます。

たとえばドキュメントサイトを構築しているものとして、関数に対するセクション (コンテントタイプ) を生成するものとします。そのセクションの下で作られるページは同一のフォーマットに従うはずです。たとえば概要説明、関数構文、利用例、備考などといった具合です。コンテント作者が標準的なフォーマットを忘れないようにするため、ページの構成を事前に与えておくことができます。

archetypes/functions.md

---
date: '{{ .Date }}'
draft: true
title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
---

関数の動作に関する簡単な説明。三人称単数、現在形を利用。たとえば以下のとおり。

`someFunction` は文字列 `s` を `n` 回繰り返して返す。

## 関数構文

```text
func someFunction(s string, n int) string
```

## 利用例

1 つまたはそれ以上の利用例を、それぞれ枠囲いのコードブロックにより表現。

## 備考

必要に応じて内容を明らかにする追加の情報。

このコンテントの本文中にテンプレートアクションを含めることもできます。ただし Hugo がそれを処理するのは一度きり、つまりコンテント生成時のみであることを忘れないでください。普通、テンプレートアクションはテンプレート内に置きます。そうすることで Hugo がサイトをビルドするたびに、そのアクションを評価します。

リーフバンドル

You can also create archetypes for leaf bundles.

For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images.

Create an archetype for galleries:

archetypes/
├── galleries/
│   ├── images/
│   │   └── .gitkeep
│   └── index.md      <-- same format as default.md
└── default.md

Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a .gitkeep file, an empty file commonly used to preserve otherwise empty directories in a Git repository.

To create a new gallery:

hugo new galleries/bryce-canyon

This produces:

content/
├── galleries/
│   └── bryce-canyon/
│       ├── images/
│       │   └── .gitkeep
│       └── index.md
└── _index.md

別のアーキタイプの利用

コマンドラインフラグ --kind を利用すると、コンテント生成時に別のアーキタイプを指定することができます。

たとえばサイト上に 2 つのセクション、つまり記事 (article) とチュートリアル (tutorial) があるとします。この 2 つのコンテントタイプごとにアーキタイプを生成します。

archetypes/
├── articles.md
├── default.md
└── tutorials.md

そして記事向けのアーキタイプを使って記事を生成します。

hugo new content articles/something.md

次にチュートリアル向けのアーキタイプを使って記事を生成します。

hugo new content --kind tutorials articles/something.md