簡単なサイトを作ってみる

Catalpa がどのような仕組みで動いているのかを知るために、実際に小さなコード片を書いていきましょう。

テンプレート処理

はじめに実験的なコードを書くためのフォルダーを用意します。ここでは D:¥mysite としました。そして、 D:¥mysite¥templates¥default.ftl と D:¥mysite¥index.md の 2 つのファイルを作成します。default.ftl は templates フォルダーの中に置くことに気を付けてください。Catalpa では templates という名前のフォルダーは特別な意味を持っています。

D:¥mysite
- templates
  - default.ftl
- index.md

上記のようなフォルダー構造ができたら、 default.ftl と index.md のファイルの中身を以下の通り入力してください。推奨文字コードは UTF-8 ですが、 Catalpa には文字コードの自動認識機能がありますので Shift_JIS や EUC-JP でファイルを作成しても構いません。

default.ftl
<!DOCTYPE html>
<HTML>
	<HEAD>
		<META charset="utf-8">
	</HEAD>
	<BODY>
		${content}
	</BODY>
</HTML>

次は index.md です。これは、 Web ページに表示されるコンテンツになるので内容を多少アレンジしても構いません。

index.md
本日は**晴天**なり。

所定のフォルダー構造に default.ftl と index.md を作ったら Catalpa を起動して D:¥mysite を開きます。

フォルダーを開くと自動的に処理が始まります。正常に終了したら ブラウザーで開く を押してください。既定のブラウザーが起動して作成された Web ページが表示されます。

この Web ページの HTML は以下のようになっています。

index.html
<!DOCTYPE html>
<HTML>
	<HEAD>
		<META charset="utf-8">
	</HEAD>
	<BODY>
		本日は**晴天**なり。

	</BODY>
</HTML>

default.ftl の ${content} 部分が index.md の中身に置き換わった形ですね。これがテンプレート処理の結果です。テンプレートを使うことで、レイアウトやドキュメント構造を担当する HTML とコンテンツ本文を分離して別々のファイルに記述できるわけです。Web サイトの各ページ・レイアウトが共通であればテンプレートを使いまわせるので、 HTML を気にせず、コンテンツ本文（*.md）を書くことに専念することができます。

マークダウン処理

さきほどの Web ページ表示では「晴天」の前後にアスタリスク（**）が表示されていたことに気付きましたか？最初の例では index.md の内容がそのまま ${content} と置き換わっただけでした。これでは、プレーン・テキストを流し込むことしかできず Web ページの表現が乏しくなってしまいます。

そこで登場するのがマークダウン処理です。default.ftl の内容を下記の通りに書き換えてください。${content} を <@markdown> と </@markdown> で囲みます。こうすることで、 index.md の内容がそのまま出力されるのではなく、マークダウン処理を施してから出力されるようになります。

default.ftl
<!DOCTYPE html>
<HTML>
	<HEAD>
		<META charset="utf-8">
	</HEAD>
	<BODY>
		<@markdown>${content}</@markdown>
	</BODY>
</HTML>

もう一度、 Catalpa で D:¥mysite を処理してみましょう。すでに、 Catalpa を起動している場合は 更新 を押すだけです。

ブラウザーの表示は以下のようになります。「晴天」の前後にあったアスタリスク（**）表示が無くなり、代わりに「晴天」の文字が強調されています。

出力された HTML も確認してみましょう。index.md でアスタリスク（**）で囲んでいた部分が <strong> タグとなって「晴天」の文字を強調していることが分かります。

index.html
<!DOCTYPE html>
<HTML>
	<HEAD>
		<META charset="utf-8">
	</HEAD>
	<BODY>
		<p>本日は<strong>晴天</strong>なり。</p>

	</BODY>
</HTML>

Markdown 記法で記述した文章を HTML に変換する、これがマークダウン処理です。Markdown はプレーン・テキストとしても読みやすく、書きやすいという特徴のある軽量マークアップ言語です。Markdown 記法を使うことで HTML を直接記述することなく、 Web ページを作成することができます。

Catalpa で使用できる Markdown 記法は Markdown 早見表で確認できます。

YAML front matter

Markdown ファイル（.md）の先頭には YAML front matter （フロント・マター）を書くことができます。YAML front matter は YAML 形式で記述可能なデータ・ブロックです。YAML front matter は、ファイルの先頭行が 3 つのハイフンで始まり、 3 つのハイフンの行で終わります。

index.md に YAML front matter を追加してみましょう。

index.md
---
title: わたしのページ
---

本日は**晴天**なり。

先頭の 3 行が YAML front matter です。ここでは title という名前のデータを定義して、その値を わたしのページ としました。（ちなみに、データの名前は自由に決めることができます。hoge でも大丈夫です。）

YAML front matter のデータは Markdown ファイル（.md）や、テンプレート・ファイル（.ftl）で参照することができます。

index.md で title データを参照してみましょう。${title} と記述することで title データを参照することができます。

index.md
---
title: わたしのページ
---

本日は**晴天**なり。

このページのタイトルは「${title}」です。

Catalpa で処理すると結果は以下のようになります。${title} の部分が置き換わっていますね。

テンプレート・ファイル（.ftl）でもデータを参照することができます。default.ftl でも title データを参照してみましょう。

default.ftl
<!DOCTYPE html>
<HTML>
	<HEAD>
		<META charset="utf-8">
		<TITLE>${title}</TITLE>
	</HEAD>
	<BODY>
		<@markdown>${content}</@markdown>
	</BODY>
</HTML>

title を参照して <TITLE> タグが出力されるように 4 行目を追加してみました。これを処理すると Web ページの表示は以下のようになります。

ブラウザーのタブをよく見てみるとタイトルが表示されていることが確認できます。

config.yml

すでに YAML front matter にデータを定義できることを学びました。

ところで、タイトルや著者名など同じデータを複数の Web ページに出力したいこともありますよね？そんなとき、それぞれの Markdown ファイル（.md）に同じデータを繰り返し定義をしなければならないのは大変です。

Catalpa には、すべての Markdown ファイル（.md）やテンプレート・ファイル（.ftl）から共通で参照できる設定ファイルがあります。それが config.yml です。

config.yml はデータ・フォルダーの直下（D:¥mysite）に配置します。

D:¥mysite
- templates
  - default.ftl
- config.yml
- index.md

config.yml
---
title: わたしのページ
author: 匿名太郎
---

このように、 config.yml には（YAML front matter と同じように） YAML 形式でデータを定義できます。これで、各 Markdown ファイル（.md）の YAML front matter で title を定義しなくても参照できるようになりました。

データ参照の優先順位: config.yml と Markdown ファイル（.md）で同じ名前のデータを定義すると、優先順位に基づくデータ参照ができます。たとえば config.yml で title を定義します。title を定義していない page-A.md と page-B.md は config.yml の title を参照する、 page-C.md では tilte を再定義して config.yml の title ではなく page-C.md で定義した title を参照する、といったことができます。

config.yml は、ユーザー定義データを記述するだけでなく、 Catalpa の動作制御にも使われます。このために、 siteurl や upload など Catalpa で予約されているいくつかの名前があります。

テンプレート・ファイルを指定する

ここまでの説明では default.ftl という名前のテンプレート・ファイルを使用してきました。これは、 Markdown ファイル（.md）でテンプレート名を指定しなかった場合に適用される既定のテンプレートです。

default.ftl 以外のテンプレート・ファイルを用意して、 Markdown ファイル（.md）で任意のテンプレートを指定することもできます。試しに sample1.ftl というテンプレート・ファイルを templates フォルダーの下に作成してみましょう。

D:¥mysite
- templates
  - default.ftl
  - sample1.ftl
- config.yml
- index.md

中身は以下のようにします。default.ftl とほとんど同じですが、表示したときに区別できるように背景色を薄い青色（background:lightblue）にしています。

sample1.ftl
<!DOCTYPE html>
<HTML>
	<HEAD>
		<META charset="utf-8">
	</HEAD>
	<BODY style="background: lightblue;">
		<@markdown>${content}</@markdown>
	</BODY>
</HTML>

次に index.md の修正です。YAML front matter に template という名前のデータを定義して、その値を sample1 とします。

index.md
---
template: sample1
title: わたしのページ
---

本日は**晴天**なり。

このページのタイトルは「${title}」です。

これで、この Markdown ファイル（index.md）に適用されるテンプレート・ファイルが sample1.ftl になります。Web ページを表示してみましょう。

背景色が薄い青色になっているので、テンプレート・ファイル sample1.ftl が適用されていることが分かります。