基本的な説明も含んで長くなりそうなので 2 回ぐらいに分ける。

環境

2019 の Intel Mac
macOS 13.2 (22D49)
node v18.14.0（brew でインストール）
npm 9.3.1（brew でインストール）

11ty のインストール

公式サイトの Getting Startedの通り進めていく。
まずは作業ディレクトリを作成して npm の初期化を行い、npm パッケージをインストールできるよう準備する。

mkdir 11ty-hands-on
cd 11ty-hands-on
npm init -y

npm init に -y を付けておくと色々聞かれないで処理が完了する。
この状態の package.json。

{
  "name": "11ty-hands-on",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

何も入れてないので、パッケージに関する情報は何もない。
では 11ty をインストールする。
公式サイトだと --save-dev が指定されていて開発環境のみで動くようにしてるけど、このディレクトリがデプロイ環境として何かをする状況が想像つかないので --save にしてる。今後でてくるコマンドも全部 `--save'。何かあっても node_modules ディレクトリをまるっと消して、開発環境向けに入れ直せばいいだけなので問題なし。
npm って global 指定しなければ作業ディレクトリ外に影響でないし、アンインストールも簡単にできるから、ちょっとパッケージ試してみようってことが気軽にできて嬉しい。昔のパッケージ管理ってあちこちに色々残っちゃったりで、環境構築はすごい慎重にやっていた記憶・・・。

npm install --save @11ty/eleventy

この状態での package.json。

{
  "name": "11ty-hands-on",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
+  "dependencies": {
+    "@11ty/eleventy": "^2.0.0"
+  }
}

+ が増えた行。
dependencies が追加され、eleventy がインストールされた。
今後は dependencies にどんなパッケージが指定されている（インストールされている）かと、scripts にどんなコマンド（npm run xxx の xxx の部分）を準備するかだけ注意する。
一度ビルドしてみて動作することを確認する。

npx @11ty/eleventy
[11ty] Wrote 0 files in 0.02 seconds (v2.0.0)

ディレクトリ構成について

公式サイトだと index.html 作ってビルドするとどうなるかとかやってるけど、そこは端折ってディレクトリ構成について。
11ty は大きく 3 つのディレクトリを意識して作業する。
一つ目はプロジェクトのルートディレクトリ。
これは npm コマンドを叩く場所（package.json がある階層）で、11ty 内でのパス設定はここからの相対パスで考えれば基本的に問題ないはず。
次は 11ty がビルドする対象の入力ファイルの設置ディレクトリ。
デフォルトではルートにある src を見るようになってる。
最後に 11ty がビルド結果を出力するディレクトリ。
ここに入ってるファイル群がデプロイ対象のファイルになる。
デフォルトではルートにある _site になってる。

- プロジェクトルート    # npm 叩くところ
  - src              # 11ty がビルドするファイルの設置場所
  - _site            # 11ty がビルドしたファイルの出力先

上記に加えて _includes と _data という２つのディレクトリも大事。
_includes はレイアウトファイルなどを設置する。
_data は 11ty がビルドする際に参照するデータの設置場所。（json 形式のファイルを配置すると site.name とか site.url とかで値が取得できる）
データの参照は色々ルールがあるけど、_data に設置しておくとグローバルデータのように参照できてるので通常困ることはない。

- プロジェクトルート    # npm 叩くところ
  - src              # 11ty がビルドするファイルの設置場所
    - _data          # データファイル（json 形式）の設置場所
  - _site            # 11ty がビルドしたファイルの出力先
  - _includes        # レイアウトファイルなどの設置場所

こんな感じ。
src 以下に設置するテンプレートファイル（11ty がビルドするファイル）、例えば index.njk（Nunjucks 形式）を配置して {{ site.url }} と書くと、_data/site.json の url を参照して記述したところに展開してくれる。
index.njk にレイアウトを適用したいときは {% include 'ファイルパス' %} と指定する。
このファイルパスの参照先が _includes からの相対パスになっているので、_includes/layouts/base.njk みたいに使いまわせるレイアウトを記述したファイルを配置しておけば、src/index.njk などから {% include 'layouts/base.njk' %} としてあげれば、記述した場所に base.njk の内容が展開される。

- プロジェクトルート    # npm 叩くところ
  - src              # 11ty がビルドするファイルの設置場所
    - _data          # データファイル（json 形式）の設置場所
  - _site            # 11ty がビルドしたファイルの出力先
  - _includes        # レイアウトファイルなどの設置場所
    - layouts        # レイアウトファイルの設置場所

その他、個人的な構成として、 Nunjucks で使える macro という機能があるけど、これは繰り返し使うちょっとした HTML などに名前をつけておいて、macro で呼び出すことでそこに HTML が展開されるみたいな使い方をする。
macro を記述したファイルは _includes/macros に配置してる。
あとは 11ty がビルドするときに入力するファイルだったり、実行する JS だったりを配置する resources というディレクトリをルートに配置している。
これらと他に必要そうなファイルを設置すると

- プロジェクトルート    # npm 叩くところ
  - resources        # 11ty の動作に直接関係しないファイルの設置場所
    - build          # npm run xxx で使用するファイルの設置場所
    - js             # npm run xxx や 11ty 内で使う（Shortcode や Filter）自前の js ファイルの設置場所
    - ogp            # ogp イメージの作成に関するファイルの設置場所
    - favicon.svg    # 各種 favicon を生成する元となる svg ファイル
  - src              # 11ty がビルドするファイルの設置場所
    - _data          # データファイル（json 形式）の設置場所
    - assets         # css、js、img などの設置場所
  - _site            # 11ty がビルドしたファイルの出力先
  - _includes        # レイアウトファイルなどの設置場所
    - layouts        # レイアウトファイルの設置場所
    - macros         # Nunjucks の macro を記述したファイルの設置場所

こんな感じになる。

npm run でコマンドを実行する

後で TailwindCSS のコンパイルとかも一緒にする形で拡張するけど先にベースだけ書いておく。
ルートにある package.json の scripts に記載すると、npm run xxx として実行することができる。
11ty のビルドや、デバッグ用サーバの起動コマンドを書いておく。（scripts 部分だけ抜粋）

"scripts": {
-  "test": "echo \"Error: no test specified\" && exit 1"
+  "build": "npx @11ty/eleventy",
+  "dev": "npx @11ty/eleventy --serve"
},

test は使わないので削除。
11ty でビルドだけするコマンドと、ビルド＋デバッグサーバの起動（ブラウザからアクセスして画面を確認できる）を行うコマンドを追加する。
npm run build とすれば、上記で叩いた npx @11ty/eleventy と同じことが実行される。

npm run build

> 11ty-hands-on@1.0.0 build
> npx @11ty/eleventy

npm run dev とすれば、build で _site に出力されたファイルを参照する開発用 Web サーバが起動する。
ポートが使われていてズレたりしなければ、通常は http://localhost:8080 でアクセスできる。

npm run dev

> 11ty-hands-on@1.0.0 dev
> npx @11ty/eleventy --serve

[11ty] Wrote 0 files in 0.14 seconds (v2.0.0)
[11ty] Watching…
[11ty] Server at http://localhost:8080/

長くなってきたので一旦ここで切る。
次回は TailwindCSS を PostCSS で構築するところまでやって基本的な環境構築までとなるはず。

11ty と TailwindCSS のビルド環境を整える - その１

SUMMARY

環境

11ty のインストール

ディレクトリ構成について

npm run でコマンドを実行する