Wyamを使った静的サイトの生成とGitHub Actionsを使ったGitHub Pagesへのデプロイ

これ is 何

Wyam を使ってブログを作成し、Github Pages でホスティング、Github Actions でデプロイさせた手順をまとめたものです。

実行環境

• Windows 10 1909
• Microsoft.NETCore.App 2.1.21

Wyam

Wyam is 何

.NET Core製の静的サイトジェネレータで、ブログやドキュメント等を markdown と Razor ファイルで作ることができます。

見た目はテンプレートが6種類あり、カスタマイズ可能で、.NET Core および C## で機能の拡張をすることもできます。

Easy! Flexible! Powerful!

ダウンロードとインストール

.NET SDK をインストールしていない場合はインストールします。2020年8月19日現在、最新の .NET Core Runtime は3.1ですが、 Wyam をインストールするために2.1の LTS もダウンロードおよびインストールします。

.NET Core SDK,および Runtime がインストールされたら、.NET Core ツールを用いて Wyam をインストールします。

dotnet tool -g Wyam.Tool

プロジェクトの作成

プロジェクトを作成したいディレクトリに移動し、ブログテンプレートを--recipe または -r オプションで生成します。

wyam new -r Blog

テンプレートが生成されたら、次のコマンドでビルドします。

wyam -r Blog

また、ビルドの際には --theme または -t オプションでテーマを指定することができます。テーマについてはこちら。

wyam -r Blog -t CleanBlog

ビルドが終わったら、ローカル環境で実行してみます。

wyam preview

あっという間にブログが出来上がりました👏

記事の編集

./input/ 内に about.md が、また ./input/posts/ 内に first-post.md が生成されています。これらのように markdown ファイルを追加および編集することで、記事の編集および追加をすることができます。

Front Matter の設定

first-post.md ファイルの先頭に以下のようなものが書かれています。

Title: First Post
Published: 1/1/2016
Tags: Introduction
---

これらは Front Matter といい、YAML や JSON フォーマットで使うことができる固有の変数です。これを使って記事にメタデータを付与することができます。Wyam では、Hexo や Hugo のような別の静的サイトジェネレータと同じ変数を使うことができるそうです。

Published の日付を未来にするとその日になるまで表示されないようなので注意。 日本時間の深夜に記事を作成して、ローカルでは表示されるのに GitHub Pages や他のデプロイ先では表示されない場合はここを疑いましょう (1敗)。

ブログを公開する

Wyam で作成したプロジェクトを GitHub のリポジトリでバージョン管理を行い、Master ブランチが更新されたら GitHub Actions でプロジェクトをビルド、およびGitHub Pagesにホスティングを行います。

GitHub Pages is 何

GitHub のリポジトリから Web サイトを直接ホストすることができるサービスです。 詳しくはこちら。

リポジトリ名が ユーザ名.github.io の場合はユーザのページに、それ以外の場合はプロジェクトのページとして扱うことができます。

Github Actions is 何

GitHub のリポジトリから、プロジェクトをビルド、テスト、デプロイすることができるサービスです。CI/CDです。 詳しくはこちら。

リポジトリが Public なら無料、Private なら従量課金らしいです。

プロジェクトの設定を変更する

GitHubにリポジトリを作成し、Wyam で作成したプロジェクトを Commit / Push します。この際 .gitignore には以下の設定を指定しておくといいでしょう。

## Wyam files
output/
config.wyam.dll
config.wyam.hash
config.wyam.packages.xml

次に、config.wyam を編集してプロジェクトの設定を行います。

BlogKeys.Title でWeb サイトのタイトルを、BlogKeys.Description でWeb サイトのトップに表示される簡単な説明を指定できます。

Settings[BlogKeys.Title] = "This is title";
Settings[BlogKeys.Description] = "Welcome!";

Web サイトを https に指定する場合は以下のオプションを有効にします。

Settings[Keys.LinksUseHttps] = true;

Web サイトで表示するカルチャ情報を設定する場合は Keys.DateTimeDisplayCulture と Keys.DateTimeInputCulture を変更します。 2020年8月19日 のように表示したい場合は Keys.DateTimeDisplayCulture に ja-JP を指定します。 日本時間を表示したい場合も同様に Keys.DateTimeInputCulture に ja-JP を指定します。

Settings[Keys.DateTimeDisplayCulture] = "ja-JP";
Settings[Keys.DateTimeInputCulture] = "ja-JP";

プロジェクトのルーティングでは、GitHub のリポジトリがユーザページ用のリポジトリの場合 (ユーザ名.github.io) と、それ以外のリポジトリ(プロジェクトリポジトリ)の場合で指定する設定が異なります。

1 ユーザページの場合

例として、GitHubユーザ名が AconCavy の場合は以下のようになります。

Settings[Keys.Host] = "aconcavy.github.io";

2 プロジェクトページの場合

プロジェクトページで作成する場合、Keys.LinkRoot にリポジトリ名を設定する必要があります。例として、リポジトリ名が Blog の場合は以下のようになります。大文字と小文字の区別があるようなので注意が必要です。

Settings[Keys.Host] = "aconcavy.github.io";
Settings[Keys.LinkRoot] = "Blog";

この設定を変更した場合、wyam preview を使ってローカルでプレビューをしようとしても、Path が localhost:5080/ のままで、正しくプレビューすることができません。そのため、--virtual-dir オプションを指定することで正しくプレビューすることができます。

wyam preview --virtual-dir Blog

プレビューのたびに毎回コマンドを打つことがめんどくさくなるので次のような bat ファイルやシェルスクリプトを作成しておくと楽になります。

@echo off
wyam -r Blog
wyam preview --virtual-dir Blog

GitHub Actions の設定

GitHub のリポジトリページに移動し、Actions タブで新しいワークフローを作成します。 Simple workflow を作成すると、新規の YAML ファイルがリポジトリの .github/workflows に作成されます。そして、作成された YAMLファイルを gh-pages.yml に変更し、次のような内容に変更します。

name: Wyam

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Setup .NET Core SDK
      uses: actions/setup-dotnet@v1.6.0
      with:
        dotnet-version: 2.1
    
    - name: Install Wyam
      run: dotnet tool install --tool-path . Wyam.Tool
    
    - name: Build static site
      run: ./wyam -r blog
      
    - name: GitHub Pages action
      uses: peaceiris/actions-gh-pages@v3.6.4
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./output

この Wyam というワークフローは master ブランチに Push または Pull Request が送られたときに、Ubuntu 環境で .NET Core SDK / Runtime のインストール、Wyam のインストール、プロジェクトのビルド、GitHub Pages へのデプロイが行われます。

注意点

1. .NET Core SDK は Wyamの対応している2.1を使用する。
2. Wyam のインストールで --tool-path . オプションを指定して Wyam ツールをビルド環境のローカルに作成する。

作成した YAML ファイルを Commit すると、GitHub Actions が有効になり、master ブランチが更新されるため、ワークフローが実行されます。そして、ワークフローのステータスが completed job になれば成功です。

GitHub Pages の設定

リポジトリが GitHub Pages の条件に満たしていれば、Settings タブに移動すると、GitHub Pages の項目が表示されます。そこで Source 欄の Branch を gh-pages に、ディレクトリを /(root) に変更して Save することで、GitHub Pagesが有効化されます。

GitHub Pagesの条件は Public リポジトリであるか、Pro 以上のライセンスであれば Private リポジトリであれば有効です。

正しく設定ができれば、ユーザページならば ユーザ名.github.io に、プロジェクトページならば ユーザ名.github.io/リポジトリ名 にプロジェクトがホスティングされます。

例として、ユーザ名が AconCavy で リポジトリ名が Blog の場合は aconcavy.github.io/Blog にホスティングされます。

まとめ

Wyam で 作成した静的 Web サイト (本ブログ) を、GitHub Actions を使って更新を自動化し、GitHub Pages でホスティングする方法をまとめました。

1. Wyam のプロジェクトを作成する。
2. Wyam のプロジェクト設定を変更する。
3. GitHub Actions の YAML を編集する。
4. GitHub Pages の設定を有効化する。

大きく分けて4つの手順で、GitHub Pages に Wyam プロジェクトをホスティングすることができます。

あとがき

とりあえず本ブログ初の投稿として、本ブログ作成までの手順の記事を簡単に書きました。今後も触った技術や何か変なものをまとめて記事にしたいと思います。