github pages入門

はじめに

今回、マニュアルの作成をgithub pagesを使ってやってみることにしました。
その際に色々と躓いたりすることがあったので備忘録を兼ねて以下のことをする方法を記載していきます。

• markdown形式でページ作成する方法
• ローカルでデバッグする方法
• ページのレイアウトをカスタマイズする方法
• ひとつのリポジトリ内で複数のページを作成する方法

markdown形式でページ作成する方法

必要なもの

• githubアカウント

注意事項

随所にスクリーンショットがありますが投稿当時のものになります。
内容が実際と異なることがありますのでご注意ください。

リポジトリを作成する

githubにログインしてリポジトリの作成をします。
自分のリポジトリ一覧の画面から「New」ボタンを選択します。

好きなリポジトリ名を入力します。
リポジトリは必ずパブリックリポジトリにしてください。
設定が完了したら「create repository」を選択します。

github pagesの設定をする

リポジトリを作成したらリポジトリの設定画面に遷移します。

下の方にスクロールしていくと「github pages」の設定項目があります。
ここで、github pagesに反映したいブランチを選択します。
(今回はmasterブランチとします)
次に、github pagesで表示させるファイルの位置を選択します。
今回はREADMEが表示されないようにdocsを選択しました。
選択が完了したら「Save」ボタンを選択します。

設定が完了するとこのようにURLが発行されます。
しかし、アクセスしても現段階ではdocsフォルダが存在しないので404が表示されてしまいます。

そこで次にテーマの選択をしていきます。

テーマを選択する

先程のgithub pagesの設定画面から「choose theme」を選択します。
そうすると様々なテーマを選択できる画面が表示されます。
テーマを決めたら「Select theme」を選択します。
今回はCaymanを選択しました。

コミット画面が開かれるので任意のコミットコメントを入力して「commit changes」を選択します。
これでdocs以下にmarkdownファイルが作成されました！

設定画面に表示されているURLにアクセスするとindex.mdの内容が選択したテーマに沿って表示されていると思います。

index.mdを自由に編集すれば簡単にページを作成していくことができます。

ローカルでデバッグする方法

必要な環境

• ruby(今回は2.7.0を使用)

前提条件

• github pagesを設定しているリポジトリをクローンしていること

デバッグ環境を作成する

以下の内容を記載したGemfileをリポジトリ直下に作成します

# frozen_string_literal: true

source "https://rubygems.org"

git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }

# gem "rails"

gem "github-pages", group: :jekyll_plugins

リポジトリ直下にて以下のコマンドを実行します
(cd docsはdocs以下にページファイルを作成している場合に実行します)
※rubyのバージョンが異なるとうまく動作しないことがあるのでご注意ください！

sudo gem install bundler
sudo bundler install
cd docs
bundle exec jekyll serve

最後のコマンドを実行後、以下の内容が表示されることでローカルホストにアクセスしてページの内容を表示できるようになります。

...しかし、選択したテーマは反映されていません
(しかも/index.mdと指定しないといけない...)

layoutファイルを用意する

テーマを反映させるためにlayoutファイルを用意します。
themeを管理しているリポジトリ一覧から選択したテーマのリポジトリを選択します。
今回はcaymanを使用しているのでcaymanのリポジトリを選択します。
リポジトリ内に_layout/default.htmlがあるのでそれをdocs/_layouts以下に配置します。(_layoutsディレクトリは各自で作成します。)
レイアウトを複数使用したい場合はわかりやすいファイル名に変更します。
(今回はdefault.htmlで進めていきます。)

index.mdを修正する

レイアウトファイルを作成しただけではまだテーマの反映はされません。
index.mdにどのレイアウトを使用するか指定して上げる必要があります。
index.mdの先頭に以下を追記します。
(レイアウトのhtmlファイル名を別のものにしている場合はそれを指定します。)

---
layout: default
---

追記後、保存しhttp://127.0.0.1:4000/にアクセスするとテーマが反映された状態で表示されるようになります

ただ、まだヘッダー部分にタイトルや説明文がありません...
設定します！

タイトルと説明文を設定する

前項にてindex.mdでレイアウトの指定をしました。
同様の場所でタイトルと説明文の設定をすることができます。
index.mdの先頭に以下のtitleとdescriptionを追記します。

---
layout: default
title: github pages sample
description: github pagesのサンプルページです！
---

これを設定するだけでタイトルと説明文を設定することができます。

configファイルを変更する

configファイルにタイトルや説明に何を指定するか設定することで本番環境でもindex.mdファイルで指定したタイトルが表示されるようになります。
リポジトリ直下にある_config.ymlの末尾に以下を追記します。

title: { { page.title } }
description: { { page.description } }

これで本番環境でもindex.mdの内容を見てタイトルと説明文を設定してくれるようになります。

ページのレイアウトをカスタマイズする方法

リポジトリ内で作成されている_layout/以下のhtmlファイルが実際のページにも反映されるのでhtmlファイルをカスタマイズすることで自分好みのレイアウトにすることができます。
今回はページ上部にある「Skip to the content.」ボタンを削除してページ内のデフォルトの文字色を変更してみます。

リンクを削除する

_layouts/default.htmlの以下の箇所を削除します。

<a id="skip-to-content" href="#content">Skip to the content.</a>

リンクボタンが消えました！簡単ですね

デフォルトの文字色を変更する

default.htmlの内容を変更するとレイアウト部分が変更されることが分かりました。
htmlファイル内にscriptやstyleを指定することでページに動作を加えたりスタイルを変更したりすることもできます。
index.htmlの末尾に以下を追記します。

<style>
    main {
        color: magenta;
    }
</style>

保存後、ページをリロードすると文字色がマゼンタに変わりました！

先程も書いたとおり、scriptを記載することもできるので、例えばトップに戻るボタンを作成することもできます。
また、htmlを編集することでページのサイドに目次を表示させることもできます。

ひとつのリポジトリ内で複数のページを作成する方法

リポジトリ内にひとつだけではなく複数のページを作る方法です。
他にも方法はあるかもですが一例と思っていただければと...

docs以下にmdファイルを置くためのディレクトリを作成する

今まではindex.mdをdocs直下においていましたがdocs以下に任意のディレクトリを作成して、その下にindex.mdを配置します。
今回はdocs/page1/index.mdとしました。
この状態でhttp://127.0.0.1:4000/page1/にアクセスします。
無事に画面が表示されました
(わかりやすいようにタイトルに~page1~を追記しています)

ページごとにレイアウトを変えたい場合はindex.mdのlayout部分をそれに合ったlayoutのファイル名に設定すれば反映することができます。

最後に

個人的にデバッグ環境の用意やレイアウトの作成部分で躓いてしまいましたが、慣れてしまえばすごく便利なツールだなと感じました。
特にmarkdown形式で書けるようにしておくことで非エンジニアの方でも簡単にページの編集ができるのでありがたいなと思います。
プルリク作成したり変更履歴の管理もできますし...