一つの大きなHTMLページを複数のMarkdownファイルに分けて管理する方法をメモしておきます。
目次
完成イメージ
例として、更新履歴ページで説明します。
こんな感じに年、月ごとにフォルダで階層を作った後、日付ごとにMarkdownファイルを作って、日ごとの更新履歴を蓄積していくとします。
content/ ├── history/ │ ├── 2023/ │ │ ├── 01/ │ │ │ ├── 2023-01-10.md │ │ │ ├── 2023-01-12.md │ │ │ ├── 2023-01-17.md │ │ │ ├── 2023-01-24.md │ │ │ ├── 2023-01-25.md │ │ │ ├── 2023-01-30.md │ │ │ └── 2023-01-31.md │ │ ├── 02/ │ │ │ ├── 2023-02-01.md │ │ │ ├── 2023-02-05.md │ │ │ ├── 2023-02-17.md │ │ │ ├── 2023-02-20.md │ │ │ └── 2023-02-24.md │ │ ├── 03/ │ │ │ ├── 2023-03-01.md │ │ │ └── 2023-03-31.md │ │ └── 04/ │ │ ├── 2023-04-02.md │ │ ├── 2023-04-10.md │ │ ├── 2023-04-12.md │ │ ├── 2023-04-14.md │ │ ├── 2023-04-18.md │ │ ├── 2023-04-19.md │ │ ├── 2023-04-21.md │ │ ├── 2023-04-24.md │ │ ├── 2023-04-27.md │ │ └── 2023-04-28.md │ └── _index.md │ ├── その他コンテンツ │ : │ : │ :
1. historyの _index.md
content/history/_index.md
--- title: "更新履歴" date: 2023-04-30 outputs: "html" ---
outputsでhtmlを指定しているところです。これにより、HTMLファイルが出力されます。
2. 各Markdownファイル (yyyy-mm-dd.md)
content/history/yyyy/mm/yyyy-mm-dd.md
--- title: "2023-04-19" --- 更新内容をここに記載
outputについては、設定ファイルのhugo.toml(v0.110.0以前まではconfig.toml1) にてcascadeで指定します。
3. 設定ファイルの編集
カスタムフォーマット「dummy」の作成
hugo.toml
# カスタムフォーマット dummy の作成
[mediaTypes]
[mediaTypes."text/dummy"]
suffixes = ["dummy"]
[outputFormats]
[outputFormats.dummy]
name = "dummy"
mediaType = "text/dummy"
baseName = "index"
isPlainText = true
notAlternative = true
suffix = "dummy"
[mediaTypes]および[outputFormats]部分で、カスタムフォーマット定義でdummyというフォーマットが使えるようにしています。
各Markdownファイルのoutputsを「dummy」にする (cascade設定)
hugo.toml
# history セクションの設定 [[cascade]] # 出力フォーマットを.dummyとする # layouts/history/single.dummy を空ファイルで用意するとファイルが出力されなくなる outputs = ['dummy'] [cascade._target] kind = "page" path = "/history/*/**"
[[cascade]]および、[cascade._target]の部分で、各historyページで省略したoutputsの指定を['dummy']としています。
ここまでの設定を行うことで、historyは_index.mdが.htmlで出力され、その他のページは.dummyで出力されるようになります。
4. layoutsでの指定
次にhistoryセクション用のレイアウトを用意しましょう。
各Markdownファイルの内容をひとまとめにする
各Markdownの内容をひとまとめにするため、リストテンプレートに以下のような内容を用意します。
layouts/history/list.html
{{ define "main" }}
{{ range (where .Site.RegularPages "Section" "history").ByDate.Reverse }}
<h2 id="{{ .Title }}">{{ .Title }}</h2>
{{ .Content }}
{{ end }}
{{ end }}
- 各ページを取得して、
.ByDate.Reverseとしていますので、date属性ごとに逆順ソートされて結合されます。 - date属性は省略していますが、設定ファイルで以下のように設定しているため、dateは
date,publishDate,lastmodが全てなかったら、ファイル名が利用されます。hugo.toml[frontmatter] # https://gohugo.io/getting-started/configuration/#configure-dates # default is... # date = ['date', 'publishDate', 'lastmod'] # lastmod = [':git', 'lastmod', 'date', 'publishDate'] date = [":default", ":filename"] # デフォルトの順で見ていって、指定がなければ最後はファイル名から設定する → historyでは dateを省略するため lastmod = ["lastmod", ":git"] # lastmod指定があればそれを使い、なければ git情報を使う。:gitを使うには`enableGitInfo = true`の指定が必要
single.dummyを空で用意する
single.dummyを空ファイルで用意することで、ファイル自体が出力されなくなります。
layouts/history/single.dummy
- 空ファイルを上記パスに置いておくだけでOKです。
5. 動作確認
これで、<サイトURL>/history/ にアクセスすると、各Markdownファイルの内容が一つになって表示されます。
6 sitemapの加工
最後に、ここはおまけですが、実は上記までの設定だと、HTML出力時に作成されるsitemap.xmlに.dummyファイルのパスが入ってしまいます。
気になるようであれば、生成後のsitemap.xml中の.dummyのパスを削除するなどの対応を入れてください。
sitemap.xml（抜粋）
： ： <url> <loc>http://localhost:1313/it/subversion/subversion_username_and_password_record_location_on_windows/</loc> <lastmod>2021-08-14T00:00:00+00:00</lastmod> </url> <url> <loc>http://localhost:1313/it/windows/tools_always_installed_in_a_windows_environment/</loc> <lastmod>2023-04-02T00:00:00+00:00</lastmod> </url> <url> <loc>http://localhost:1313/history/2023/04/28/index.dummy</loc> <lastmod>2023-04-28T10:15:44+09:00</lastmod> </url> <url> <loc>http://localhost:1313/history/2023/04/27/index.dummy</loc> <lastmod>2023-04-27T21:39:02+09:00</lastmod> </url> ： ：