GitHub Pages の Jekyll でブログサイトを構築する

## 前提
* Webサイトの構成要素(html、CSS、JavaScript)の基本的な知識がある
* GitとGithubについて、基本的な使い方を知っている
* markdownとStaticSiteGenerator(SSG)がどんなものか知っている

## 事前知識
* GitHub Pages は、曰く「GitHub を通じてホストされ、公開されるパブリックな Web ページです。」また、下記のとおり禁止される用途があるので、ご注意ください
* markdownファイルをレポジトリにアップロードすると、デフォルトのSSGである Jekyll が動作して、html に変換してくれます（自動的にデプロイされる）
* Jekyll は RubyGem なので、Ruby実行環境を構築すれば、ローカルでビルドしてhtml表示できますが、Visual Studio Code(VScode)に機能拡張をインストールすればhtmlの簡易表示が可能です
* デザインを規定するさまざまなテーマが利用可能です

### 参考

禁止される用途:

https://docs.github.com/ja/pages/getting-started-with-github-pages/about-github-pages#prohibited-uses

## ステップ別手順

### ステップ1：最小限のファイル(3ファイル)でブログ風サイトを作る

1. レポジトリを作成して、GitHub Pages設定
2. 設定ファイルとホームページを設定
3. 投稿(post)を書く
4. (オプション)固定ページ(page)を作る

### 1. レポジトリを作成して、GitHub Pages設定

下記を参照してください。ここではレポジトリ名を「<ユーザー名>.github.io」、可視性を「パブリック」、公開元に「/(root)」を設定したものとして話を進めます。

GitHub Pages サイトを作成する: 

https://docs.github.com/ja/pages/getting-started-with-github-pages/creating-a-github-pages-site

### 2. 設定ファイルとホームページを設定

#### 設定ファイル

ルートディレクトリに`_config.yml`を作成します。最低限の設定（タイトルとテーマ）を指定します。

```yml:_config.yml
title: <your site title>
theme: jekyll-theme-minimal
```

GitHub Pages でサポートされているテーマは次のとおりです。レイアウトはページの構造を決定します。
post(投稿)レイアウトがあるテーマはブログ向けを想定していると考えられます。

サポートテーマ:

https://pages.github.com/themes/

|theme|THEME-NAME|_layouts|license|
|---|---|---|---|
|Architect|jekyll-theme-architect|default.html|CC0-1.0|
|Cayman|jekyll-theme-cayman|default.html|CC0-1.0|
|Dinky|jekyll-theme-dinky|default.html|CC0-1.0|
|Hacker|jekyll-theme-hacker|default.html, post.html|CC0-1.0|
|Leap day|jekyll-theme-leap-day|default.html|CC0-1.0|
|Merlot|jekyll-theme-merlot|default.html|CC0-1.0|
|Midnight|jekyll-theme-midnight|default.html|CC0-1.0|
|Minima|minima|base.html, home.html,<br/>page.html, post.html|MIT|
|Minimal|jekyll-theme-minimal|default.html, post.html|CC0-1.0|
|Modernist|jekyll-theme-modernist|default.html|CC0-1.0|
|Slate|jekyll-theme-slate|default.html|CC0-1.0|
|Tactile|jekyll-theme-tactile|default.html|CC0-1.0|
|Time machine|jekyll-theme-time-machine|default.html|CC0-1.0|

> サポートされているテーマを使うには、「theme: THEME-NAME」と入力します。その際に、THEME-NAME はテーマのリポジトリの _config.yml に示されているテーマ名前に置き換えます (ほとんどのテーマは、jekyll-theme-NAME の名前付け規則に従います)。 サポートされているテーマの一覧については、GitHub Pages サイトの「サポートされているテーマ」を参照してください。 たとえば、最小テーマを選ぶには、「theme: jekyll-theme-minimal」と入力します。

Jekyll を使用して GitHub Pages サイトにテーマを追加する: 

https://docs.github.com/ja/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll

#### ホームページ

あと、ホームページ(トップページ)を`index.html`として作っておきます。
先頭の`---`で囲まれている部分は、フロントマターといってメタ情報を記載するところです。
ここではページレイアウトとして`default`を指定しています。
動的な部分はhtmlのテンプレート言語Liquidで記述します。
投稿のコレクションをループさせて一覧表示することを想定しています。

```Liquid:index.html
---
layout: default
title: Home
---
<h1>Latest Posts</h1>

<ul>
  {% for post in site.posts %}
    <li>
  　  {{ post.date | date: "%Y-%m-%d" }}
      <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
      {{ post.excerpt }}
    </li>
  {% endfor %}
</ul>
```

テーマが「Minima」であれは、レイアウトとして`home.html`があるので、以下で済ませられます。

```Liquid:index.md
---
layout: home
---
```

### 3. 投稿（post）作成

markdownファイルを書いて、「_posts」フォルダにアップロードします。
この際、ファイル名は、`YEAR-MONTH-DAY-title.md`とします。
公開時のURLパスは`/YEAR/MONTH/DAY/title.html`となります。
フロントマターでメタ情報が記述できるのは同じです。よく使われるフロントマターは以下のとおり。

|フロントマター|内容|
|---|---|
|layout|レイアウト|
|title|タイトル|
|auther|著者|
|date|日時|
|category, categories|投稿を分類します。URLの一部になります。|
|tags|投稿にタグをつけます。URLに影響しません。|

フロントマターについては下記を参照してください。

https://jekyllrb-ja.github.io/docs/front-matter/

https://docs.github.com/ja/contributing/writing-for-github-docs/using-yaml-frontmatter

投稿の例を以下に示します。

```
---
layout: post
title: "「なぜ働いていると本が読めなくなるのか」感想あるいはアテンション・エコノミーへの対峙"
author: pipin68k 
date: 2025-02-21
tags:
 - 読書感想
 - なぜ働いていると本が読めなくなるのか
 - アテンション・エコノミー
 - ナラティブ
---
- Table of Content
{:toc}

## はじめに

タイトルの「なぜ働いていると本が読めなくなるのか」に対して、著者はその原因を「新自由主義化した社会で、仕事へのフルコミットを求められ、ノイズを含む読書が敬遠されている」と結論付けて「みんな、半身で働ける社会を目指そう」と呼び掛けています。
```

投稿の作成は下記を参照してください。

Step by Step チュートリアル 8. ブログ: 

https://jekyllrb-ja.github.io/docs/step-by-step/08-blogging/

Posts（ポスト）: 

https://jekyllrb-ja.github.io/docs/posts/

ここまでの作業で、レポジトリの構成は次のようになります。

```
.
├── _config.yml
├── _posts
│   └── 2025-02-21-reading-note.md
└── index.html # or index.md
```

### 4. (オプション)固定ページ(page)を作る

Aboutなどの日付に基づかないページは、htmlファイルまたはmarkdownファイルで作成して配置します。

固定ページの作成は下記を参照してください。

Pages（ページ）: 

https://jekyllrb-ja.github.io/docs/pages/

## ステップ2：デザインをカスタマイズしたい

前節の作業ではhtmlを書いていないのに、Webページが閲覧できるようになりました。
何故でしょうか。
PostやPage等のコンテンツと設定情報を元に、指定したテーマを用いてJekyllがhtmlを生成してくれているからです。
テーマはおおむね次のような構成をもっています。
各フォルダの役割はリンク先を参照してください。

ディレクトリ構成: 

https://jekyllrb-ja.github.io/docs/structure/

ディレクトリ構成の例

```
.
├── _config.yml
├── _includes
│   ├── footer.html
│   └── header.html
├── _layouts
│   ├── default.html
│   └── post.html
├── _posts
│   ├── 2021-06-10-fair-is-foul.md
│   └── 2022-02-22-to-be-or-not.md
├── _sass
├── _site
├── assets
│   ├─css
│   ├── style.scss
│   ├─fonts
│   ├─img
│   ├── logo.png
│   ├─js
│   └── scale.fix.js
└── index.html
```

指定していないファイルはデフォルトのファイルが使われます。
つまり、同階層に同名のファイルがあれば、デフォルトのファイルではなくそちらが使われます。
設定を上書きでき、これでカスタマイズが可能になっています。
下記を参照ください。

https://jekyllrb-ja.github.io/docs/themes/#%E3%83%86%E3%83%BC%E3%83%9E%E3%81%AE%E3%83%87%E3%83%95%E3%82%A9%E3%83%AB%E3%83%88%E3%82%92%E4%B8%8A%E6%9B%B8%E3%81%8D%E3%81%99%E3%82%8B

使用しているテーマの構成はテーマ自体のGitHubレポジトリを参照してください。

## ステップ3：サポートされていないテーマを使う

「GitHub Pages でサポートされているテーマ以外のテーマが使いたい」場合は、ローカルにRuby実行環境を構築するのがよいでしょう。構築方法は下記のクイックスタートを参照ください。

クイックスタート: 

https://jekyllrb-ja.github.io/docs/

デフォルトでは、`jekyll new myblog`すると、`theme: minima`のサイトが構築されます。

テーマの導入方法は、そのテーマのGitHubレポジトリのREADMEに書かれています。

## 構築事例

テーマ「minima」での作成例をあげておきます。ご参考まで。

https://pipin68k.github.io/

## 出典・参考

* GitHub Pages のドキュメント: 
 
https://docs.github.com/ja/pages

* jekyllのサイト: 

https://jekyllrb-ja.github.io/