更新日: 2023 / 12 / 20

Jekyllでページを作成する方法

カテゴリー: コーディング

Jekyllでページを作る方法を紹介します。

Jekyllにはテンプレート機能があるので、別の場所(_includes)で作成したHTMLファイルをテンプレートに挿入したり、用意したデータを取得して自動的に表示するといったこともできます。

このページではJekyllのページの作り方と合わせて、基本的なテンプレートの機能についても解説していきます。

  1. Jekyllのフォルダ構成について

  2. Jekyllでページを作る方法

    1. インクルード機能を使ってヘッダーを表示する
    2. レイアウトテンプレート機能を使ってベースレイアウトを作成する
    3. CSSファイルやJavascriptファイルを読み込む
    4. ページごとにtitleタグやメタタグを書き換える
    5. ページごとに使用するレイアウトテンプレートを変更する
    6. ページごとにCSSスタイルを変更する

  3. Jekyllで作ったページをローカル環境で確認する方法

  4. Jekyllを使ったページの作成でよくあるエラーとその対処法

    1. プレビュー(ビルド)でエラーになる
    2. JekyllでCSSが読み込まれないエラー
    3. Jekyllで画像が表示されないエラー

  5. まとめ

Jekyllのフォルダ構成について

ページを作り始める前にJekyllのフォルダ構成について理解しておく必要があります。

Jekyllでは挿入できるHTMLファイルの置き場所やベースとなるテンプレートの置き場所が以下のように決まっています(_config.ymlで設定を変更することもできます)。

  • _layouts: ベース(レイアウト)テンプレートをここに配置
  • _includes: テンプレートに挿入するHTMLファイルをここに配置
  • _sass: SCSSファイルをここに配置
  • _data: テンプレートで使用するデータ(ymlファイル)をここに配置

デフォルトで指定されているフォルダにはフォルダ名の前に_をつけます。

この他に以下のフォルダがJekyllのデフォルトで設定されています。

  • _posts: 記事ファイルを配置
  • _drafts: 下書きの記事ファイルを配置
  • _site: 生成時に自動的に作成されるフォルダ

全体の構造はこちらのようになっています。

├── _config.yml
├── _data
│   └── members.yml
├── _drafts
│   ├── begin-with-the-crazy-ideas.md
│   └── on-simplicity-in-technology.md
├── _includes
│   ├── footer.html
│   └── header.html
├── _layouts
│   ├── default.html
│   └── post.html
├── _posts
│   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
│   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
│   ├── _base.scss
│   └── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html

それぞれのフォルダなどのさらに詳しい解説についてはこちらの公式ドキュメントをご覧ください。

Jekyllでページを作る方法

Jekyllでページを作る一番簡単な方法は、プロジェクトの直下にindex.htmlなどのHTMLファイルを作成し、普通にHTMLでコーディングする方法です。

例えば次のようなコードを作成します。

<!DOCTYPE html>
<html lang="ja">
<head>
  <title>Jekyllで作成したページ</title>
</head>
<body>
  <header>
    <h1>Jekyllで作成したページ</h1>
  </header>
</body>
</html>

このままだと普通のHTMLファイルなのでJekyllを使わなくてもページを表示できます。

Jekyllではレイアウトテンプレートとインクルード(挿入)テンプレートに分けて管理できるので上記のコードを分割していきます。

インクルード機能を使ってヘッダーを表示する

まずはヘッダーを分割します。テンプレートに挿入するパーツを作る場合は、_includesフォルダに入れます。

次のような構成になります。

├── _includes
│   └── header.html
└── index.html

header.htmlに先ほどのコードのヘッダー部分を入れ、index.htmlに挿入します。

挿入するには{% include example.html %}のようなタグを使用します。

<!-- _includes/header.html -->
<header>
  <h1>Jekyllで作成したページ</h1>
</header>

<!-- index.html -->
---
---

<!DOCTYPE html>
<html lang="ja">
<head>
  <title>Jekyllで作成したページ</title>
</head>
<body>
  {% include header.html %}
</body>
</html>

こんな感じで分割したHTMLファイルを好きな場所に挿入できます。

Jekyllのタグを使用する場合は必ず1行目と2行目に---を書いておきます。これを書かないとインクルードタグを認識してくれません。

{% include ... %}タグはdiv要素や、head要素の中にも入れることができます。

_includesフォルダ内にさらにフォルダを入れて階層化することもできます。その場合は次のように書きます。

{% include global/header.html %}

{% include main/toppage/slider.html %}

レイアウトテンプレート機能を使ってベースレイアウトを作成する

インクルードタグだけでも便利に使えますが、複数ページを作る場合はheadタグなど重複する部分が出てきます。

ページごとに共通の部分をまとめられるのがレイアウトテンプレートで、_layoutsフォルダに作成します。

├── _includes
│   └── header.html
├── _layouts
│   └── default.html
└── index.html
<!-- _layouts/default.html -->
<!DOCTYPE html>
<html lang="ja">
<head>
  <title>Jekyllで作成したページ</title>
</head>
<body>
  {{ content }}
</body>
</html>

<!-- index.html -->
---
layout: default
---

{% include header.html %}

_layoutsフォルダに共通部分を書いたHTMLファイルを入れておいて、{{ content }}タグを設置します。

index.htmlなどのページではこの{{ content }}の中身を作成する感じになります。

またindex.htmlの方で、layout: defaultで使用するレイアウトテンプレートを指定しておきます。

CSSファイルやJavascriptファイルを読み込む

レイアウトテンプレートの方にもインクルードタグを使えるので、ヘッダーやフッターなど共通パーツは全てレイアウトテンプレートに入れておくこともできます。

また、CSSファイルやJavascriptファイルの読み込みもレイアウトテンプレート方でやっておきましょう。

CSSファイルはindex.htmlと同じようにプロジェクトフォルダの直下に置くこともできますが、assetsフォルダを作ってまとめておくこともできます。

├── _includes
│   └── header.html
├── _layouts
│   └── default.html
├── assets
│   └── style.css
└── index.html

ここまでまとめるとレイアウトテンプレートは次のようになります。

<!-- _layouts/default.html -->
<!DOCTYPE html>
<html lang="ja">
<head>
  <title>Jekyllで作成したページ</title>

  <!-- CSSファイルの読み込み -->
  <link rel="stylesheet" href="./assets/style.css">
</head>
<body>
  <!-- ヘッダー -->
  {% include header.html %}

  <div id="main">
    {{ content }}
  </div>

  <!-- フッター -->
  {% include footer.html %}

  <!-- JSファイルの読み込み -->
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
</body>
</html>

<!-- index.html -->
---
layout: default
---

<p>トップページの中身</p>

ページごとにtitleタグやメタタグを書き換える

Jekyllで複数ページを作成する場合、ページタイトルやMetaタグなどページごとに変更したいデータがあります。

そのようなページごとに異なるデータは、ページテンプレートに自由に記述できます。

例えば次のような感じです。

<!-- index.html -->
---
layout: default
title: ページタイトル
description: ページの説明文
thumbnail: https://example.com/images/page-thumbnail.png
permalink: /about/toppage.html
---

<p>トップページの中身</p>

ここではページタイトル、説明文、サムネイル画像、パーマリンクを設定しました。

パーマリンクは通常、Jekyllのプロジェクトに作成した通りに自動的に設定されますが、変更することもできます。

ページテンプレートに書いたデータを取得するには、{{ page.title }}のように書きます。

<!-- _layouts/default.html -->
<!DOCTYPE html>
<html lang="ja">
<head>
  <title>{{ page.title }}</title>
  <meta name="description" content="{{ page.description }}">
  <link rel="canonical" href="https://example.com{{ page.permalink }}">

  <!-- Twitterメタタグ -->
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:title" content="{{ page.title }}">
  <meta name="twitter:description" content="{{ page.description }}">
  <meta name="twitter:image" content="{{ page.thumbnail }}">

  <!-- CSSファイルの読み込み -->
  <link rel="stylesheet" href="./assets/style.css">
</head>
<body>
  <!-- 中身省略 -->
</body>
</html>

ページごとに使用するレイアウトテンプレートを変更する

下層ページを作成しているときに、ページごとにヘッダーを変えたいとか、レイアウトを変えたいといったこともあります。

そのような場合は下層ページ用のレイアウトテンプレートを作って、ページテンプレートのlayoutのところでページごとに指定すればOKです。

<!-- index.html -->
---
layout: page
---

<p>下層ページの中身</p>

このときページのレイアウトも変更して、例えば下層ページのみサイドバーを表示するといったこともできます。

<!-- _layouts/page.html -->
<!DOCTYPE html>
<html lang="ja">
<head>
  <!-- 省略 -->
</head>
<body>
  <!-- ヘッダー -->
  {% include header.html %}

  <div id="main">
    {{ content }}
  </div>

  <!-- サイドバーを表示 -->
  <div id="sidebar">
    {% include page/sidebar.html %}
  </div>

  <!-- フッター -->
  {% include footer.html %}
</body>
</html>

ページごとにCSSスタイルを変更する

ページごとに設定できるデータ(FrontMatter)を使うことでCSSを分けることもできます。

<!-- index.html -->
---
layout: page
page_css: page_style
---

<p>下層ページの中身</p>

ページタイトルと同様に、{{ page.page_css }}でファイル名を取得してレイアウトテンプレート内で使用します。

ここではpage_cssがある場合はそれを使用し、ない場合はデフォルトのCSSファイルを表示するようにしています。

<!-- _layouts/default.html -->
<!DOCTYPE html>
<html lang="ja">
<head>
  <title>{{ page.title }}</title>

  <!-- CSSファイルの読み込み -->
  {% if page.page_css %}
    <link rel="stylesheet" href="./assets/{{ page.page_css }}.css">
  {% else %}
    <link rel="stylesheet" href="./assets/style.css">
  {% endif %}
</head>
<body>
  <!-- 中身省略 -->
</body>
</html>

ifとかelseはJekyllのテンプレートエンジンで使われているLiquidのものです。

Jekyllで作ったページをローカル環境で確認する方法

Jekyllで作成したページをローカル環境で確認したり、HTMLファイルとして生成するにはターミナル(コマンドプロンプト)で次のコマンドを入力します。

コマンドはプロジェクトフォルダに移動してから入力します。

// プロジェクトフォルダに移動する
cd mysite

// ローカル環境でページを表示する
bundle exec jekyll serve

// HTMLファイルを生成する
bundle exec jekyll build

ローカル環境で確認したり、生成すると_siteというフォルダが自動的に作成されます。

この中身をレンタルサーバーなどにアップロードすればブラウザ上で作成したページを確認できるようになります。

Jekyllを使ったページの作成でよくあるエラーとその対処法

Jekyllでページを作成しているときによく発生するエラーとその対処方法をいくつか紹介します。

プレビュー(ビルド)でエラーになる

ターミナルでserveやbuildコマンドを打ったときにでるエラーで一番多いのが次のようなエラーです。

Error: Could not locate the included file 'test.html' in any of ["/Users/name/mywebsite/_includes",

これはtest.htmlというファイルが見つからないというエラーで、{% include test.html %}タグで指定したファイルのパスが違う場合に発生します。

ファイル名やパスをもう一度確認して修正してください。

JekyllでCSSが読み込まれないエラー

CSSやJavascriptなどのファイルが読み込まれない原因は以下のようなことが考えられます。

  • URLの書き間違い
  • 相対パスで指定している場合、相対パスが間違っている

絶対パスで書いてる場合はURLに間違いがないかをチェックしましょう。

相対パスで書いている場合は、そのページから見たときにCSSファイルの場所が正しいパスになってるかを確認してください。

Jekyllで画像が表示されないエラー

画像が表示されない場合は次のようなことが考えられます。

  • パスが間違っている
  • 指定したURLに画像がない
  • CSSで非表示にされている

パスの間違いの他にも、指定したURLに画像がそもそもない場合は何も表示されません。

また、CSSで要素が非表示にされている可能性もあるのでそちらも確認してみてください。

まとめ

Jekyllでページを作成する方法を紹介しました。

Jekyllのような静的サイトジェネレータでもメタタグやページごとのタイトル設定ができるのでSEO対策も可能です。

小規模で更新頻度が少ないWebサイトならWordpressよりもHTMLでサイトを作成する方が低コストで運用できるのでおすすめです。