mohikanz Advent Calendar 2020 ～13日目～

こちらは mohikanz Advent Calendar 2020 13日目のエントリです。12日目はくじゃくさんの初めての英語カンファレンス #PloneConf2020 に参加してきましたでした。海外カンファレンスに参加された感想とのことです。海外カンファレンスは日本時間の深夜に開催されることが多いので深夜帯カンファレンスの参加はかなり厳しいすよね…マジ乙です…！

WordPress から HUGO へ乗り換えた話

WordPress のサイトを HUGO へ移行し GitHub Pages で公開するまで設定します。理由は以下のとおりです。

Markdown でﾌﾞﾖｸﾞを書きたい
月間PV数の割にサーバの性能がよすぎる
- 無料枠などを利用してサーバ料金を浮かせたい
- サイトを構成する合計データサイズが1GB未満なのにサーバのディスクサイズがデカすぎる

作業の流れ

作業は以下の流れで進めていきます。

WordPress から HUGO へ乗り換えた話
HUGO 環境の準備
WordPress コンテンツを Markdown へ変換
テーマにあわせてコンテンツデータを調整
- ここが鬼門
コンテンツ作成
サイトの移転
旧サイトの破棄

作業環境

作業環境は以下のとおりです。

WordPress サーバ
- OS バージョン: CentOS7.3.1611
HUGO 実行環境
- OS バージョン: Windows 10
- HUGO バージョン: v0.65.3-211
- WSL: Ubuntu 18.04.2

HUGO 環境の準備

HUGO の実行環境を用意します。

HUGO のインストール

公式ドキュメントをもとに HUGO をインストールしようと思ったら、プラグイン等がうまく動かないトラブルが発生したため WSL を導入して apt-get でインストールします。

1
2
3
4
 $ sudo apt-get upgrade
 $ sudo apt-get install hugo
 $ hugo version
Hugo Static Site Generator v0.65.3-211BA42A/extended linux/amd64 BuildDate: 2020-02-23T10:07:00Z

新規サイトの作成とテーマの導入

Quick Start にあるとおり新規サイトの作成と HUGO テーマの導入を進めます。

新規サイトの作成

以下コマンドで新規サイトを作成します。サイト名はわかりやすい名前を設定します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
 $ hugo new site (新規プロジェクト名)
Congratulations! Your new Hugo site is created in /mnt/c/Users/…/Desktop/(新規プロジェクト名).

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

テーマの導入

HUGO 用の様々なテーマが公式サイトで公開されています。今回はシンタックスハイライトがイケてる hugo-theme-zzo を導入します。

1
2
3
 $ cd (新規プロジェクト名)/
 $ git init
 $ git submodule add https://github.com/zzossig/hugo-theme-zzo.git themes/zzo

細かい設定は後ほど調整します！

WordPress コンテンツを Markdown へ変換

WordPress サーバへログインし現在の WordPress コンテンツを Markdown へ変換します。

wordpress-to-hugo-exporter プラグインのインストール

WordPress のコンテンツを HUGO 向けのコンテンツに変換するプラグイン wordpress-to-hugo-exporter をインストールします。ただ、WordpressからHUGOへ移行する方法にあるとおり WordPress の管理画面でのプラグイン検索には引っかからなかったので、以下コマンドで配置しスクリプトを実行します。

1
2
3
4
5
6
7
8
9
 $ cd $WORDPRESS_HOME/wp-content/plugins/
 $ git clone https://github.com/SchumacherFM/wordpress-to-hugo-exporter.git
 $ cd wordpress-to-hugo-exporter/
 $ ll
合計 32
-rw-rw-r-- 1 kusanagi kusanagi  4507 12月  7 20:23 README.md
-rw-rw-r-- 1 kusanagi kusanagi  1127 12月  7 20:23 hugo-export-cli.php
-rw-rw-r-- 1 kusanagi kusanagi 16845 12月  7 20:23 hugo-export.php
drwxrwxr-x 3 kusanagi kusanagi    39 12月  7 20:23 includes

コンテンツの変換

PHP スクリプトを実行し WordPress のコンテンツを HUGO 向けコンテンツへ変換します。変換が完了すると /tmp 配下に ZIP ファイルができあがります。

1
2
3
4
5
6
7
 $ php hugo-export-cli.php 
[INFO] tmp folder not found, use default. You could invoke php hugo-export-cli.php with an extra argument as the temporary folder path if needful.

This is your file!
/tmp/wp-hugo.zip
 $ ll -h /tmp/wp-hugo.zip
-rw-rw-r-- 1 kusanagi kusanagi 611M 12月  7 20:25 /tmp/wp-hugo.zip

テーマにあわせてコンテンツデータを調整

ここからがけっこう大変な作業なのですべて終わるまで1年かかりました。(ほぼ私のやる気の問題)

コンテンツデータを HUGO 環境へ転送

scp コマンドなどで ZIP ファイルを HUGO の実行環境へ転送します。コマンドは環境によるので割愛します。

コンテンツの配置

転送した ZIP ファイルを HUGO 環境上で展開しそれぞれ以下のように配置します。

content ディレクトリ

ZIP ファイルを展開し記事ファイルを content ディレクトリへコピーします。

1
2
3
 $ mkdir temp&&mv wp-hugo.zip temp&&cd temp
 $ unzip wp-hugo.zip
 $ cp -ar temp/hugo-export/posts/ (新規プロジェクト名)/content/

static ディレクトリ

画像データを static ディレクトリへコピーします。

1
2
 $ mkdir -p (新規プロジェクト名)/static/images
 $ cp -ar temp/hugo-export/misapress/* (新規プロジェクト名)/static/images/

HUGO 設定ファイルの作成

Configuration を参考に設定ファイルを作っていきます。

config.toml の設定

HUGO サイトに関する設定ファイルを作成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 $ vi config/_default/config.toml
baseURL = "https://getter.misalin.net" # The URL of your site.
title = "おいでよさばかんの沼 " # Title of your site
theme = "zzo" # Name of Zzo theme folder in `themes/`.

#defaultContentLanguage = "ja" # Default language to use (if you setup multilingual)
#defaultContentLanguageInSubdir = true # baseURL/en/, baseURL/kr/ ...
hasCJKLanguage = true # Set `true` for Chinese/Japanese/Korean languages.
languageCode = "ja"

summaryLength = 70 # The length of a post description on a list page.
buildFuture = true # if true, we can use future date for talks page

copyright = "©{year}, All Rights Reserved" # copyright symbol: $copy; current year: {year}
timeout = 10000
enableEmoji = true
paginate = 13 # Number of items per page in paginated lists.
rssLimit = 100

enableGitInfo = false # When true, the modified date will appear on a summary and single page. Since GitHub info needs to be fetched, this feature will slow down to build depending on a page number you have
googleAnalytics = ""

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      hardWraps = true
      unsafe = true
      xHTML = true
  [markup.highlight]
    codeFences = true
    lineNos = true
    lineNumbersInTable = true
    noClasses = false
  [markup.tableOfContents]
    endLevel = 3
    ordered = false
    startLevel = 2

[outputs]
  home = ["HTML", "RSS", "JSON"]

[taxonomies]
  category = "categories"
  tag = "tags"
  series = "series"

menus.toml の設定

サイト内右上にあるメニューの内容を定義します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 $ vi config/_default/menus.toml
[[main]]
  identifier = "about"
  name = "About"
  url = "about"
  weight = 1

[[main]]
  identifier = "archive"
  name = "Archive"
  url = "archive"
  weight = 2

[[main]]
  identifier = "posts"
  name = "Posts"
  url = "posts"
  weight = 3

[[main]]
  identifier = "slides"
  name = "Slides"
  url = "slides"
  weight = 4

params.toml の設定

各種パラメータを設定します。設定が長いので一部を抜粋します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 $ vi config/_default/params.toml
logoText = "おいでよさばかんの沼" # Logo text that appears in the site navigation bar.
logoType = "short" # long, short -> short: squre shape includes logo text, long: rectangle shape not includes logo text
logo = true # Logo that appears in the site navigation bar.
description = "参加したイベントやいろいろなメモ" # for SEO
:
themeOptions = ["dark", "light", "hacker", "solarized", "kimbie"] # select options for site color theme
notAllowedTypesInHome = ["contact", "talks", "about", "showcase", "slides"] # not allowed page types in home page. type can be set in front matter or 
default to folder name.
notAllowedTypesInHomeSidebar = ["about", "archive", "showcase", "talks"] # not allowed page types in home page sidebar(recent post titles).
notAllowedTypesInArchive = ["about", "talks", "showcase", "slides"] # not allowed page types in archive page
:
# whoami: usage - home page sidebar, single page bottom of post. all values can be empty
myname = "靴ひも伍長"
#email = "zzossig@gmail.com"
whoami = "Cloud in'腐'rastructure engineer."
bioImageUrl = "/images/icons/onnanoko.jpg" # image url like "http//..." or "images/anyfoldername/mybioimage.jpg" If not set, we find a avatar image in root/static/images/whoami/avatar.(png|jpg|svg)
useGravatar = false # we use this option highest priority
location = "Tokyo, Japan"
organization = "東海道らぐ"
link = "https://github.com/misato8310"
:
[socialOptions] # if set, social icons will show up.
#  email = "mailto:your@email.com"
#  phone = ""
#  facebook = "http://example.org/"
  twitter = "https://twitter.com/_EOF_83_EOF_"
  github = "https://github.com/misato8310"
:

サイト表示の確認

hugo server を実行後ブラウザで http://localhost:1313/ へアクセスすることでサイト表示をプレビューできます。すべてのコンテンツデータを含めてサイトの表示を確認したいときは以下のオプションを使います。

1
 $ hugo server -D

下書き状態のものを除外してプレビューするときは以下のオプションを使います。

1
 $ hugo server -E

コンテンツデータの修正

メニュー部分の編集

Zzo docs を参照しながらぼちぼち作成していきます。

サイドメニューの編集

現行サイトにある Twitter のタイムラインをサイドメニューへ埋め込みます。タイムラインのコードはタイムラインを埋め込む方法に生成方法が記載されています。

1
2
3
4
5
 $ mkdir -p layouts/partials/sidebar
 $ cp -a themes/zzo/layouts/partials/sidebar/sidebar-home.html layouts/partials/sidebar/sidebar-home.html
 $ vi layouts/partials/sidebar/sidebar-home.html
## 5行目あたりに追記
             <a class="twitter-timeline" data-lang="ja" data-width="240" data-height="400" data-theme="dark" href="https://twitter.com/_EOF_83_EOF_?ref_src=twsrc%5Etfw">Tweets by _EOF_83_EOF_</a> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

表示崩れの修正

記事内で使用している画像のリンクなどが引き継がれず表示崩れが発生している場合があります。その際はリンクを修正します。

wp-content パスの削除

WordPress サイトではないのに wp-content のパスが残っているのは違和感あるので修正します。具体的には以下のような感じです。

移転前URL例
- https://getter.misalin.net/misapress/wp-content/uploads/2019/12/ergodox-ez-02.jpg
移転後URL例
- https://getter.misalin.net/images/misapress/2019/12/ergodox-ez-02.jpg

コンテンツデータ内のパスから /wp-content/uploads を除外します。

1
2
 $ cd content/
 $ find . -type f | xargs sed -i -e 's#/wp-content/uploads##g'

あわせて画像URLのパスを相対パスにするため手動で修正します。(もっといい方法あったとおもうけど浮かばなかった)

コンテンツ作成

ページの作成やサイドメニューなどいろいろカスタマイズします。

メニューの追加

右上にメニューを追加します。

メニューページの作成

about ページを例にメニューページの作成方法を記載します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 $ mkdir content/about/&&cd content/about/
 $ hugo new content/about/index.md
---
title: "About"
author: 靴ひも 伍長
type: about
url: /about

---

# 本サイトについて

本サイトは靴ひも伍長のアドベントカレンダーや参加したイベント、いろいろなメモ置き場です。
なお、本サイトに掲載している情報でなにか問題が発生しても一切責任を負いかねます／(^o^)＼

# 凡例

よくあるアレです。

* 先頭が # で始まる文字列
    * コマンドです。
        - `#` は root ユーザのプロンプト
        - `$` は一般ユーザのプロンプト
* [Enter] について
    * Enter キーを押下してほしいの意味です。

独自メニューページの用意

slides ページを新規で定義し今まで作成したスライド一覧を掲載します。

slides ページの作成

以下のような感じでページを作成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
 $ hugo new content/slides/index.md
---
title: "slides"
author: 靴ひも 伍長
type: slides
url: /slides

---

# スライド一覧

LTで発表した資料は [speakerdeck](https://speakerdeck.com/misato8310) にあげています。

## 2020年

## 2019年

|平成最後に開発合宿へ参加した話|あなたと ErgoDox EZ、今すぐ購入|CentOS8 ｷﾀ━━━━(ﾟ∀ﾟ)━━━━!!|
|-|-|-|
|<script async class="speakerdeck-embed" data-id="ab659ff960644715a0c4d60cc4cd4f6b" data-ratio="1.33333333333333" src="//speakerdeck.com/assets/embed.js"></script>|<script async class="speakerdeck-embed" data-id="49f9c8dd73d4495fb2b4af821512e10c" data-ratio="1.77777777777778" src="//speakerdeck.com/assets/embed.js"></script>|<script async class="speakerdeck-embed" data-id="b05f7b3d25ee4351bad1c7c78d17fc6b" data-ratio="1.77777777777778" src="//speakerdeck.com/assets/embed.js"></script>|
:

type: slides の定義

type: slides という type はテーマでは定義されていないため新規で定義します。

1
2
 $ mkdir -p layouts/slides
 $ cp -a themes/zzo/layouts/about/single.html layouts/slides/single.html

Posts 一覧からの除外

登録した type を Posts 一覧などに表示させたくないときは以下へカテゴリを追記します。

1
2
3
4
5
 $ vi config/_default/params.toml
## 以下変更
notAllowedTypesInHome = ["contact", "talks", "about", "showcase", "slides"] # not allowed page types in home page. type can be set in front matter or default to folder name.
notAllowedTypesInHomeSidebar = ["about", "archive", "showcase", "talks"] # not allowed page types in home page sidebar(recent post titles).
notAllowedTypesInArchive = ["about", "talks", "showcase", "slides"] # not allowed page types in archive page

サイトの移転

諸々調整や修正が完了したらサイトの移転作業を行います。

GitHub Actions の設定

GitHub Actions を利用して HUGO のビルドからデプロイまで自動化します。

リポジトリの作成

GitHub Actions を利用して以下を自動化するため以下のリポジトリを作成します。

HUGO プロジェクトのリポジトリ
- リポジトリ名は my-blog と設定
- ビルド後 GitHub Pages リポジトリへデプロイ
- 公開範囲はプライベートでOK
デプロイ先のリポジトリ(GitHub Pages を設定するリポジトリ)
- リポジトリ名は (username).github.io と設定
- 公開範囲はパブリック

HUGO プロジェクトのリポジトリにキーを登録

それぞれのリポジトリにデプロイキー、シークレットキーを登録します。my-blog リポジトリ側に登録したシークレットキーを用いて (username).github.io リポジトリへビルドしたファイルをデプロイするイメージです。この概念イマイチつかめなくてなんとか理解するまで半日かかりました。

デプロイキー
- 登録先リポジトリ: (username).github.io
- 手順は公式サイトを参照
- ssh-keygen(パスフレーズなし) で生成した 公開鍵 を登録
シークレットキー
- 登録先リポジトリ: my-blog
- 手順は公式サイトを参照
- ssh-keygen(パスフレーズなし) で生成した 秘密鍵 を登録
- シークレットキー登録の際 ACTIONS_DEPLOY_KEY を指定した前提で進めます

GitHub Pages action の導入

my-blog リポジトリに GitHub Pages action を導入し以下の作業を自動化します。

HUGO サイトのビルド
GitHub Pages へのデプロイ

ワークフローファイルは Getting started と GitHub Actions で Hugo のビルドからデプロイまでを自動化するための環境を整えるを参考にし作成します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 $ vi .github/workflows/gh-pages.yml
name: github pages

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.65.3'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: misato8310/(username).github.io
          publish_branch: main
          cname: getter.misalin.net

GitHub Pages でサイトを公開

my-blog リポジトリの登録

ローカルにある HUGO プロジェクトに my-blog リポジトリの情報を登録します。

1
2
 $ git init
 $ git remote add origin (my-blog リポジトリのURL)

デプロイの確認

my-blog リポジトリを更新した際に (username).github.io リポジトリへ自動でデプロイされるか確認します。(既存ドメインの場合SSL証明書が利用できるまで時間かかるかも)

1
2
3
 $ git add -A
 $ git commit -m "First commit"
 $ git push -u origin main

Push が完了したら my-blog リポジトリの Actions タブから GitHub Pages action のワークフローが正常に実行されているか確認します。500MB弱のデータでも数分でデプロイしてくれるので、時間がかかる場合は一度ワークフローを中止してエラーメッセージを確認したほうがいいです。6時間かけた私からのアドヴァイスです。

github-pages-deploy

独自ドメインの設定

デプロイが完了したら (username).github.io リポジトリに独自ドメインを設定します。

DNS レコード切り替え

以下のように DNS レコードを変更し新しいレコードが正引きできるようになるまで待ちます。SSL証明書も発行されるのでしばらく待ちます。

Name	Type	Value
getter.misalin.net	CNAME	(username).github.io

以下へアクセスし旧サイトと新サイト両方で同じURLでページ閲覧できることを確認します。

https://getter.misalin.net

問題なければ移転作業は完了！お疲れ様自分…(ヽ´ω`)

旧サイトの破棄

GitHub Pages への切り替えが完了したら旧サーバの破棄等を行います。これは忘れがちなので時期が空きそうならカレンダーとかに登録しておくと良いかも。

おわり

HUGO はどうすればやりたいことを実現できるのか私のググり方が良くなくて、移行が完了するまで年単位でかかってしまいました。HUGO は悪くないです。年間ずっと調査していたわけじゃなくて途中で私が飽きて放置してしまった期間が長かった感じです。