この記事は、Progate Path コミュニティ Advent Calendar 2024 の 13 日目の記事です。
前編では、 Eleventy
を使って HTML をビルドする環境をハンズオン形式で作成します。途中で出てくるコマンドなどは、 Mac を前提としているため、 Windows を使っている場合は適宜読み替えてください。
Eleventy を使ってローカル開発環境を作成する
まずは、 Eleventy
を使って静的ファイルを生成する環境を用意します。ここでは以下の流れで進めていきます。
-
Eleventy
とは -
Eleventy
のインストール方法 -
Eleventy
の設定
もしすぐに環境を利用したい場合は、 こちら にリポジトリを用意したので利用してください。
Eleventy とは
Eleventy
は、シンプルで非常に柔軟な静的サイトジェネレーターです。 公式サイト によると、ビルドが他のジェネレーターツールよりも高速であることが示されており、また特定の JavaScript フレームワークに依存することなく使用できるため、単純な HTML / CSS / JavaScript で構成されたリソースを生成するのに向いています。
一つだけ依存しているものを挙げると、 Node.js
のバージョンが 18
以上である必要があります。もしターミナルで以下のコマンドを実行して、バージョン番号が 18
未満である場合、先に Node.js
のバージョンアップをしてください。
$ node -v
v20.11.0 # 使用しているバージョンにより出力が変わります
Eleventy のインストール方法
Eleventy
のインストールは、公式サイトの ドキュメント ページに記載のある手順で進めることが出来ますが、以下に簡単な説明を添えて対応の流れを示します。
1. 作業用のフォルダを作成する
まずは、 Eleventy
を導入して作業をするためのフォルダを作成しましょう。ターミナルで以下のコマンドを実行してください。 path/to/project-name
については、環境や好みに応じて自由に変更してください。
$ mkdir /path/to/project-name && cd /path/to/project-name
# 例: mkdir ~/project/eleventy-sample && cd ~/project/eleventy-sample
また、作業用のフォルダが作成できたら、 VSCode で該当のフォルダを開いておきましょう。ターミナルで以下のコマンドを実行してください。
$ code .
# . は、カレントディレクトリを参照することを意味しています。
2. Eleventy をインストールする
次に、 フォルダを Node.js
のプロジェクトとして初期化した後、 Eleventy
をインストールします。ターミナルで以下のコマンドを実行してください。
$ npm init -y
$ npm install @11ty/eleventy
$ npm install --save-dev rimraf
フォルダ内に、 package.json
ファイルと、 node_modules
フォルダが生成されていれば成功しています。
また、 npm scripts についても Eleventy
を実行するための内容に変更しておきましょう。 package.json
の scripts
プロパティを以下のように変更してください。
{
"scripts": {
"clean": "rimraf dist",
"build": "npm run clean && NODE_ENV=production eleventy",
"build:dev": "npm run clean && NODE_ENV=development eleventy",
"watch": "eleventy --watch",
"start": "NODE_ENV=development eleventy --serve"
}
}
3. Eleventy の設定
Eleventy
の設定は、 eleventy.config.js
ファイルで管理します。インストールを実行してもこのファイルは生成されないため、ターミナルで以下のコマンドを実行して作成してください。
$ touch eleventy.config.js
最初に設定するのは、入力や出力などの必要最低限の設定です。 eleventy.config.js
に以下の内容を記述してください。
module.exports = async (eleventyConfig) => {
return {
dir: {
input: "src",
output: "dist",
includes: "_includes",
layouts: "_layouts",
data: "_data",
},
};
};
dir
オブジェクト内にある各プロパティについて、以下に簡単な説明を記載します。
-
input
- 入力(バンドル元)フォルダを指定できます。
src
は、単一のフォルダ名を指定していますが、 glob を使うことも可能です
- 入力(バンドル元)フォルダを指定できます。
-
output
- 出力(バンドル先)フォルダを指定できます。こちらも
input
プロパティと同様に glob を使うことが可能です
- 出力(バンドル先)フォルダを指定できます。こちらも
-
includes
- テンプレートファイルに読み込むためのファイルが格納されるフォルダを指定できます。たとえば、ヘッダーやフッターのファイルを分離して
includes
に指定したフォルダに格納することで、他のページで共通パーツとして呼び出せます
- テンプレートファイルに読み込むためのファイルが格納されるフォルダを指定できます。たとえば、ヘッダーやフッターのファイルを分離して
-
layouts
- インクルードと似ていますが、レイアウトを指定するためのファイルが格納されるフォルダを指定できます。
-
data
- テンプレートで使用するデータ用ファイルが格納されるフォルダを指定できます。
Eleventy を使って静的ファイルを出力する
ここまでで必要最低限の設定が出来たので、 /src
フォルダに作成したファイルをバンドルして、 /dist
フォルダに出力できるようにしてみましょう。
1. テンプレートファイルを用意する
この記事では、最小限の設定でファイルの出力ができるようにしていきましょう。ターミナルで以下のコマンドを実行してください。
$ mkdir -p src/_data && touch src/_data/site.json
$ mkdir src/_includes && touch src/_includes/footer.njk src/_includes/header.njk
$ mkdir src/_layouts && touch src/_layouts/base.njk
$ mkdir src/pages && touch src/pages/index.njk
.njk
という見慣れない拡張子が登場しましたが、これは Nunjucks というテンプレートエンジンを使うことを示しています。詳細な説明は公式サイトに委ねますが、 HTML を拡張して、変数やフィルタ、ループなど JavaScript の処理を利用できるようにしたものです。
Evelenty
では、 Nunjucks
以外にも多数のテンプレートエンジンに対応しています。
1-1. site.json にメタデータを定義する
site.json
には、サイトのメタデータを記述します。今回は以下のようにしてみました。
{
"name": "サイト名",
"description": "サイトの説明",
"url": "https://example.com",
"keywords": "キーワード1, キーワード2, キーワード3",
"ogpImage": "https://example.com/ogp.jpg",
"ogpUrl": "https://example.com"
}
1-2. header.njk と footer.njk にヘッダーとフッターの HTML を記述する
header.njk
には、共通で使い回すためのヘッダーを記述します。
<header>
<nav>
<div>
<a href="/">Your Site</a>
</div>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
<li><a href="/contact">Contact</a></li>
</ul>
</nav>
</header>
footer.njk
には、共通で使い回すためのフッターを記述します。
<footer>
<p>© 2024 {{ site.name }}</p>
</footer>
1-3. base.njk にレイアウト用 HTML を記述する
base.njk
には、ページの骨格となるレイアウト用の HTML を記述します。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>{{ title }} | {{ site.name }}</title>
<meta name="description" content="{{ description }}" />
<meta name="keywords" content="{{ keywords }}" />
<meta name="format-detection" content="telephone=no,email=no,address=no" />
<meta property="og:title" content="{{ site.name }}" />
<meta property="og:description" content="{{ description }}" />
<meta property="og:image" content="{{ site.ogpImage }}" />
<meta property="og:url" content="{{ ogpUrl }}" />
<meta property="og:type" content="website" />
<link rel="icon" href="/assets/common/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" href="/styles/main.css" />
<script src="/scripts/main.js" />
</head>
<body>
{% include "header.njk" %}
<main>{{ content | safe }}</main>
{% include "footer.njk" %}
</body>
</html>
1-4. index.njk にトップページ用の HTML を記述する
index.njk
には、ページのメタデータとなる Front Matter と、HTML を記述します。
---
permalink: /index.html
layout: base.njk
title: ホームページ
description: トップページの説明
keywords: キーワード1, キーワード2, キーワード3
ogpUrl: https://example.com
---
<div class="hero">
<h1>Welcome to {{ site.name }}</h1>
<p>{{ description }}</p>
</div>
冒頭の Front Matter
に記述されている permalink
と layout
について、以下に簡単な説明を記載します。
-
permalink
- 出力ディレクトリ(今回は
dist
)内のどこにファイルを出力するかをカスタマイズできるプロパティです。今回は入力がpages/index.njk
であるため、ここを記述しないとdist/pages/index.html
として出力されるため、記述しておきましょう
- 出力ディレクトリ(今回は
-
layout
- 使用するレイアウトファイルを指定するためのプロパティです
ここまで出来たら、ファイルが出力されるか確認しましょう。ターミナルで以下のコマンドを実行してください。
$ npm run build
dist/index.html
ファイルが生成されていれば OK です。
以上で Eleventy
を使って HTML を出力できる環境が作成できました。 CSS や JavaScript のビルドについては、後編でハンズオンをします。