Tags: ,

git管理前提のhugoプロジェクトの作り方

Table of Contents

Github ActionsでGithub Pagesを更新させるために、そのWebページのソースとなるHugoプロジェクトを作ったあと、gitリポジトリ化する手順。

1. gitリポジトリを前提としたHugoプロジェクトの作成

雛形の時点でgitリポジトリ化する。

コマンド列:

$ hugo new site MY-SITE
$ cd MY-SITE/
$ git init
$ git add .
$ git commit -m "[init]"

2. .gitignoreを加える

Hugo用.gitignoreファイル内容:

/public/
/resources/_gen/
/assets/jsconfig.json
/.hugo_build.lock
hugo_stats.json

コマンド列(emacsはテキストファイルの編集):

$ emacs .gitignore
$ git add .gitignore
$ git commit -m "[add] .gitignore"

3. テーマインストール

テーマは以下から選ぶ:

このにあるテーマはgitリポジトリで公開されているので、git submoduleでインストールする:

$ git submodule add https://github.com/joeroe/risotto.git themes/risotto
$ git commit -m "[add] theme"

A. hugoについて

hugoは、Markdown形式で書いた文書ファイル(拡張子: .md)群を、HTMLファイル化して、一覧ページももつWebサイトを構成するファイル群に変換するシステム。

生成するWebサイトのHTMLのソースとなるディレクトリは、「Hugoプロジェクト」と呼ぶ。

hugoコマンドのインストール

Hugoのコマンドは、各プラットフォームのパッケージマネージャー経由で導入する。

よく使うhugoコマンド

hugoでは、すべてコマンドライン上でhugoコマンドを使用して、Webサイトを構築する処理を行う。

  • hugo new site SITE-NAME: 空っぽのHugoプロジェクトのファイル群を、SITE-NAME/ディレクトリ以下に生成するコマンド
  • hugo new ARTICLE-FILE.md: 記事の雛形となるcontent/ARTICLE-FILE.mdファイルを生成するコマンド
  • hugo server: プレビューとなるWebサーバを、http://localhost:1313/に立ち上げるコマンド
  • hugo: public/ディレクトリ以下に、HTMLファイルのWebサイト一式を生成するコマンド

Hugoプロジェクトのファイル構成

  • サイト設定用ファイル:
    • hugo.toml: hugoコマンドが解釈する設定ファイル
    • themes/: Webサイトのテーマ(となるHugoプロジェクト)を置く場所
  • 文書用ファイル:
    • content/: 個別のWebページのソースとなる文書データのmdファイルを置く場所
    • static/: 全記事から参照できるファイル(画像など)を置く場所
  • サイトデザイン用ファイル:
    • layouts/: 各Webページの枠部分や、トップページなどの一覧ページを生成するためのテンプレートファイル群
    • archetypes/: hugo newで作るファイルの雛形となるmdファイルがある場所
    • data/: layoutのテンプレートが参照する設定ファイルを置く場所
    • assets/: layoutのテンプレートで使用するファイル(スクリプトやスタイルシートなど)のソースを置く場所

hugoのテーマシステム

hugoプロジェクトのテーマというのは、既存のHugoサイトのlayouts/等のサイトデザインファイル群を継承する仕組み。

hugoは、Webページを生成する処理で必要なファイルを参照するとき、Hugoサイト自身に存在しなければ、テーマファイルの中の同名ファイルを使用するようになっている。 (テーマの一部を上書きするときは、該当ファイルをHugoサイト直下の同名の位置へコピーして編集する)

このため、Hugoプロジェクトの構成はは、継承元となるテーマのテンプレートコードに依存したものとなり、テーマによって大きく違うものになる (扱うcontent/下のファイル名を特定したテーマもある)。

  • 現在は、テーマに限らず任意のファイルで、他プロジェクトのファイルを参照可能になるHugo Moduleも備わっている

B. Hugo Modules

テーマに限らず、content/やstatic/なども他のHugoプロジェクトから継承可能にするのがHugo Modules。 hugo modコマンドで操作する。

  • hugo modを使う場合は、テーマでもgit submoduleは使わなくなる

共通の記事や画像のデータがあるサイトを、ファイルコピーせずに管理できるようになる。 ただし、hugo modを使うには、hugo単体ではなく、gitとgolangのランタイムもインストールされている必要がある。

hugo mod initで有効化したあとは、hugo.tomlに以下のように書くだけで、テーマが適用されるようになる。

(pathの値はgitリポジトリのURLだが、https://は外す)

[module]
  [[module.imports]]
    path = 'github.com/joeroe/risotto'

注: Hugo Moduleを使う場合、layouts/等が直接継承されるので、hugo.toml中のtheme = "risotto"の行は消さなくてはいけない。

bellbind avatar
bellbind
https://github.com/bellbind

Related