Hugo + Academic テーマを使ったブログの作り方

15481 ワード
Hugo hugo-theme academic Hugo テキストリンク

はじめに

Hugoはいいぞ

hugo-themeで一番人気のあるAcademicを使って
カッコいいホームページ作ったので、設定のやり方とかを共有したいと思います。

作成したブログ
https://max-blog.ga/

ソースコード
https://github.com/harumaxy/MyBlog

Hugo + Academic テーマでブログを書く

Hugoでブログを書くために最初にやったのは、テーマ選びです。

  • おしゃれ
  • SEOに優れてる
  • レスポンシブ
  • 人気がある

を探してみた。
最終的にGithubのStarが一番多いやつにしました。
やはりStar数は正義！

参考にしたランキングサイト
https://hugo-theme-ranking.oika.me/

Academicテーマについて

Academic 公式サイト

GitHubで一番⭐Starが多いHugoテーマ

このHugoテーマのターゲットは、大学や研究機関に属する研究者のポートフォリオ。
(RとかLatexなど、研究用のソフトウェアに互換する設定項目が多数見受けられる。)

でも、SEO対策やレスポンシブ対応がされていて
個人ブログや企業サイトなど、一般的なHPビルダーとしての使用にも耐えうるというスタンス。

デモを見る限りでも、スタイリッシュかつ多機能でいろいろな人に使われているのは分かりました。
でも、日本語情報が少ないので使い方を調べるのに困りました。

でもなんとか、ブログとしての運用までこぎつけたので、
備忘録を残しておきます。

Academic テーマの使い方

Academicを使う前に

Hugoがはじめての人は、公式サイトのDocumentを読んで、
基本的な概念を頭に入れておきましょう。

といっても、全部読んでるときりがないので、読むべきとこだけ抜粋します。
最低でもQuick Start、さらにContent Managementのセクション全体を読めば良いでしょう。

install

academic-kickstartのリポジトリをクローンするのが簡単

git clone https://github.com/sourcethemes/academic-kickstart.git My_Website

Academic themeはgit submoduleになってるので更新する。

cd My_Website
git submodule update --init --recursive

デフォルト状態のページを確認したければ、以下のコマンドを実行して localhost:1313 にアクセスしてみてください。

hugo server

注意 : 真っ白な画面が出たら、git submodule updateを忘れていてthemesをロードできてない可能性が高いです

最小限の設定

プロジェクトルートにあるconfig.tomlではなく、
/config/_default/フォルダにある4つの.tomlファイルを編集します。

  • config.toml
  • language.toml
  • menus.toml
  • params.toml

最小限必要だと思う設定を書いたので、参考にしてみて。

config.toml
# /config/_default/config.toml

# サイトの基本設定
title = "Maxのブログ"
baseurl = "https://max-blog.ga/"
copyright = "[email protected]"

# 言語設定
defaultContentLanguage = "ja"  # 出力後の <html lang=""> の部分
hasCJKLanguage = true          # trueにすると、日中韓の言語で文字カウントとかが正しく動作する
language.toml
# /config/_default/language.toml

# 最初は英語がonになっているので、コメントアウトしておく
# [en]
#   languageCode = "en-us"

[ja]
  languageCode = "ja"
menus.toml
# /config/_default/menus.toml

# themeのpartial部品を編集しなくても、ここで設定した項目で自動的にメニューバーを生成される。

# [[main]] 辞書のリスト型
[[main]]
  name = "Home"
  url = "#about"  # / をつけないで #anchor を書くと、ホーム画面内のアンカーリンクになる
  weight = 10     # weightが軽いほどメニューの左側に表示される 


[[main]]
  name = "Skills"
  url = "#skills"
  weight = 15

[[main]]
  name = "Post"
  url = "/post"   # urlは、/content/ フォルダーを基準にした相対パスを指定する
  weight = 20
params.toml
# /config/_default/params.toml

# 見た目に大きく関わる設定ファイル

theme = "Ocean"   # AcademicのTheme。気軽にカラーリングなどを変えられる
font_size = "M"   # フォントサイズ。(初期設定だとL)

# コードブロックのsyntax hilightのスタイル。
# Academic Theme との組み合わせによってはコードが見づらくなるので、必ず検討する。
# https://highlightjs.org/static/demo/ からスタイル名を探して入れる
highlight_style = "vs2015"

#   Examples: "Mon, Jan 2, 2006" or "2006-01-02"
date_format = "2006/01/02"
#   Examples: "3:04 pm" or "15:04"
time_format = "3:04 PM"

# カスタムCSSを使いたいなら書く
plugins_css = ["custom"]

# Google analytics
[marketing]
  google_analytics = ""
  google_tag_manager = ""

これらの設定は、.tomlに元々のデフォルト値が書いてある。

気分によっていろいろ試したい人は、
元の部分をコメントアウトして、よく使う設定をファイルのトップにまとめて書く
とアクセスしやすくなっていいと思う。

最小限の/content/フォルダ構成

Hugoは、プロジェクトルートにある content フォルダ以下にある
ページバンドルに対して、自動的にルーティングを作成します。
(ページバンドルが何かは、Page Bundleを見てください。)

で、academic-kickstartをgit cloneした直後の/content/フォルダはこんな感じです。

content
├── authors
│   └── admin
├── home
│   ├── about.md
│   ├── accomplishments.md
│   ├── contact.md
│   ├── demo.md
│   ├── experience.md
│   ├── featured.md
│   ├── hero.md
│   ├── index.md
│   ├── people.md
│   ├── posts.md
│   ├── projects.md
│   ├── publications.md
│   ├── skills.md
│   ├── slider.md
│   ├── tags.md
│   └── talks.md
├── post
│   └── _index.md
├── publication
│   └── _index.md
└── talk
    └── _index.md

content/home/フォルダはズバリ、ルーティングで言うところの"/"ルートに該当します。

何やらたくさんのmdファイルが入っていますね。
これらはwidgetと呼ばれ、homeフォルダにファイルを追加するだけでhomeページにパーツを追加できるというものです。

index.md ファイル以外は必須ではないので、必要ないウィジェットは削除します。
すべてのウィジェットは/themes/academic/exampleSite/content/home に入ってるので、必要になったらそこからコピーすれば問題ありません。

あと、個人的なブログでは publication(出版物) や talk(講演) といったセクションは必要ないので、
それらのセクションフォルダも削除します。

僕のブログの/content/フォルダの構成はこんな感じになりました。

content
├── authors
│   └── admin
├── home
│   ├── about.md
│   ├── index.md
│   ├── posts.md
│   └── skills.md
└── post
    └── _index.md

自己紹介を書こう

Academicテーマで作成されたサイトは、複数人のauthorで運用できるように工夫されています。

content/author フォルダに存在するページバンドル1単位がauthor1人分に対応しているようです。

デフォルトだと、admin というauthorが存在します。
英語のドキュメントを解読するのがめんどかったので、僕は hugo server コマンドで
ホットリロードしながらデフォルトの admin/_index.md を改変して自分のプロフィールを作成しました。

こんな感じ

content/authors
└── max  # リネームした
    ├── _index.md
    └── avatar.jpg

ここで設定した情報は、 content/home/about.md ウィジェットに表示されます。

# content/authors/max/_index.md
---
# Display name
name: Max

# Username (this should match the folder name)
authors:
- max

superuser: true

# Role/position
role: 野良プログラマ

# bio = biographyの略。自己紹介、経歴、趣味など
bio: 転職活動中。

# 関心事のリスト
interests:
- Flutter & Dart
- Go
- Rust

# ソーシャルアイコン。font awesomeを使ってるっぽい
social:
- icon: envelope
  icon_pack: fas
  link: 'mailto:test@[email protected]'
- icon: twitter
  icon_pack: fab
  link: https://twitter.com/maxy8653
- icon: github
  icon_pack: fab
  link: https://github.com/harumaxy

# ユーザーグループ。個人ブログならいらないかも？
user_groups:
-  Programmers
---

このサイトはしがないプログラマの独り言を書くブログ。
Hugo + Academicテーマ を使って作成してます。

# content/home/about.md
+++
# About widget.
widget = "about"  
headless = true  
active = true  
weight = 20  

# タイトルを日本語にしとく
title = "自己紹介"

# 表示するauthorを指定する
author = "max"
+++

avatar.jpgを変更

デフォルトで、avatar.jpgという画像ファイルが入ってますが、
これを差し替えることでアバター画像を変えられます。

  1. 元の avatar.jpg を削除
  2. 好きな画像を同じ場所に入れる
  3. avatar.jpgにリネーム

.pngでも行けるかは知らん

.mdに入っている +++ とか --- について

これは、Front Matterという、markdownに TOML や YAML でメタデータを付けるための
markdownの仕様です。

Front Matterの情報を使って、バックエンドではGoがhtml/templateパッケージでレンダリングします。

どっちかというとAcademicテーマではなくHugo本体の仕様です。

+++ もしくは --- で囲まれた範囲にメタデータを記述できます。

  • +++ : toml
  • --- : yaml

Hugo的にはどっちを使ってもいいんですが、
Academic Themeはところどころ +++ と --- が混ざってるので混乱しないように。

記事を書いてみる

ここまでで設定は完了です。
次はmarkdownで記事を書いてみましょう。

hugo new [path] コマンドで、/content/ フォルダ以下にmarkdownコンテンツが作成されます。

hugo new post/first-post.md
# もしくは
hugo new post/first-post

上のコマンドは、拡張子の .md まで書いてあるので markdown ファイルが作成されます。

下のコマンドは、拡張子まで書かないことで、ページバンドルフォルダが作成されます。

first-post
└── index.md
  • markdown記事単体が書きたいなら .md あり
  • 記事内で使う画像ファイルなどを記事と一緒にフォルダにまとめたいなら .md なし

と覚えましょう

まとめ

いかがだったでしょうか。

Hugoの爆速ビルド+Firebaseの爆速ホスティングは
WordPress + PHP + MySQL みたいなスタックよりUX, DXが優れてると思うので、
エンジニアの方はぜひ試して見てはいかがでしょうか。

そのうちCircleCIでGitHubへのpushからFirebaseへのデプロイまで自動化したい