tanaka's Programming Memo

プログラミングについてのメモ。

GitHub Pagesのマークダウンにテーマを設定する

GitHub

はじめに

GitHubの機能の一つである GitHub Pages を使えば、無料で自分のWebサイトや作品のWebサイトをインターネット上で公開することができます。マークダウンで書かれたファイルは自動的にHTMLに変換して表示します。とても便利ですが、デフォルトのスタイルはものすごく質素です(図1)。

f:id:am1tanaka:20170201180641p:plain:h200
(図1)デフォルトのGitHub Pages

GitHub Pages は Jekyll というツールを使ってマークダウンファイルをHTMLに変換していて、あらかじめいくつかのテーマが組み込まれています。それを適用すれば見た目を改善することができます。




方針

方針は以下の2点です。

  • 作品を作成しているリポジトリーとWebページを共存させる(Webページ専用のリポジトリーは作らない)
  • GitHub Page用のデータは master ブランチの docs フォルダーに入れる



前提

以下の環境を前提とします。



GitHub Pages用のフォルダーの作成

プロジェクトフォルダーに docs フォルダーを作成して、GitHubにプッシュします。

  • GitHub Desktop(f:id:am1tanaka:20170125215602p:plain) を起動
  • 作業したいリポジトリーを右クリックして、[Show in Explorer]を選択してエクスプローラーで開く
    • 作業手順を確認したいだけで、作品がない場合は、GitHub Desktop で新しいプロジェクトを作成して、上記の作業をしてください
  • 開いたフォルダーに docs という名前のフォルダーを新規に作成
  • README.md をコピーして、 docs フォルダー内に貼り付ける
  • GitHub Desktop に切り替える
  • 表示を[Changes]に変更
  • [Summary]欄に[docsフォルダーを追加]などのように入力
  • [Commit to master]を押す
  • 右上の[Sync]を押す

以上で、 GitHub Pages 用のフォルダーができました。


GitHubでページの設定

フォルダーができたので、GitHub Pagesをそのフォルダーに割り当てます。

f:id:am1tanaka:20170201182344p:plain
図3 Settings

  • 画面を下にスクロールさせて [GitHub Pages]の欄を表示
  • Source 欄のコンボボックスをクリック > [master branch /docs folder]を選択 > [Save]ボタンを押す(図4)

f:id:am1tanaka:20170201182552p:plain
図4 GitHub Pagesを docs フォルダーに設定

GitHub Pages の設定をした欄の下に表示するための URL が表示される(図5)ので、そこをクリックしてください。ビルドが完了し次第(1分程度かかる可能性があります)、 README.md が成形されて表示されます(図6)。
f:id:am1tanaka:20170201183804p:plain
図5 作品ページのURL

f:id:am1tanaka:20170201211851p:plain
図6 最初のGitHub Pages


テーマを適用

簡素な画面に、組み込みテーマを適用します。

f:id:am1tanaka:20170201212255p:plain
図7 Change Themeボタン

  • 採用したテーマをクリックする
    • クリックすると、そのテーマでの描画イメージがページの下に表示されるので、確認してください
  • 画面右の[Select Theme]をクリックする(図8)

f:id:am1tanaka:20170201213024p:plain
図8 Select Theme

  • デフォルトのマークダウンが表示されるので、ひとまず画面下の[Commit Changes]をクリック(図9)

f:id:am1tanaka:20170201213239p:plain
図9 Commit Changes

以上で適用完了です。作品の GitHub Pages を再読み込みしてください。マークダウンの使い方が記されたページが、選択したテーマで表示されます(図10)。
f:id:am1tanaka:20170201213449p:plain
図10 テーマが適用されたページ


ページ内容を構築する

テーマの設定ができたので、あとはページの内容を作品のものに書き換えます。

ページに必要な画像や素材の準備

作品の紹介に使う画像ファイルや、UnityのWebGLをビルドしたフォルダーを、 docs フォルダーにコピーします。たとえば、以下のような構成にします。

  • docs/images フォルダー内に img0.png と img1.png
  • docs/webgl フォルダー内に Unity でビルドした WebGL のプロジェクト

ページを作成

作品ページをマークダウンで作成します。

  • GitHub Desktop に切り替える
  • 画面右上の[Sync]を押して、GitHub の更新を取得
  • Atom などのエディターで、作品フォルダー内の docs/README.md を開く
  • あらかじめ入力されているマークダウンの例は不要なので削除
  • 作品の紹介マークダウンを入力する。以下、例
# 正月休み課題「鶏Bomb2017」
ver 170108
<p>
<a href="webgl/index.html" target="_blank">
<img src="images/img0.png" height="240px" alt="タイトル画面">
<img src="images/img1.png" height="240px" alt="ゲーム画面">
<p>ゲームで遊ぶ</p>
</a>
</p>

# ルール
画面の上から卵が降ってきます。これを爆風で孵化させてください。

卵が下に落ちて割れたらゲームオーバーです。

# 操作方法
- 画面をタップした場所に爆弾が置かれます
- 爆弾は一定時間が経過すると爆発します
- 爆風で卵を孵してください
- 爆風に触れた爆弾も、爆発します

# 高得点のヒント
- 卵は画面下で孵化させるほど高得点です
- 一つの爆風で、複数の卵を孵すと得点が増えます
- 誘爆させた爆風で孵化させると、得点が増えます

# 既知のバグ
まだ開発中のため、バグがあります。

バグの確認や報告は[こちら](https://github.com/tanakaedu/ToriBomb2017/issues)へどうぞ。

---
Copyright(C)2017 YuTanaka
  • 上書き保存する
  • GitHub Desktop に切り替える
  • [Changes]に切り替えて、 [Summary]に「ドキュメントの作成」などと入力して[Commit to master]を押す
  • 右上の[Sync]を押す

以上で完了です。作品ページを再読み込みしてください。適用したテーマで、作品ページが表示されるようになります。変更が反映するまでに1分程度かかる可能性がありますので、変更が確認できない場合は、しばらく待ってから再読み込みをしてみてください。


ページの上段の変更

一度設定したレイアウトは、 [Settings]メニューから別のテーマを選択すれば切り替えることができます。切り替わるのに1分程度かかる場合があるので、設定したらしばらく待ってください。

ページの先頭は、リポジトリー名とリポジトリーの Description が自動的に挿入されます(図11)。
f:id:am1tanaka:20170201220508p:plain
図11 ページの先頭部分

Description を変更したい場合は、以下のようにします。

  • リポジトリーページを開いて、 Description の右の [Edit]をクリック

f:id:am1tanaka:20170201220955p:plain

  • テキストボックスの内容を変更して、右の[Save]を押す

以上だけでは、ページは更新されないようです。再構築をするには、Settingsから一度別のテーマを設定してから、元のテーマに設定しなおしてください。


まとめ

以上で、デフォルトの状態よりも見た目がよいページにすることができます。似合うテーマを色々と試してみてください。

以下、作例です。


ここでのやり方は、GitHubに予め用意された定型のテーマやレイアウトでの利用にとどまります。自由に見た目を変更したい場合は、 Jekyll というWebサイト生成ツールを利用します。英語ですが、手順が紹介されているページがこちらにあります。興味があれば、調べてみてください。


参考URL