Catalpa がどのような仕組みで動いているのかを知るために、 実際に小さなコード片を書いていきましょう。
はじめに実験的なコードを書くためのフォルダーを用意します。ここでは D:¥mysite
としました。そして、 D:¥mysite
と D:¥mysite
の 2 つのファイルを作成します。default
は templates
フォルダーの中に置くことに気を付けてください。Catalpa では templates
という名前のフォルダーは特別な意味を持っています。
上記のようなフォルダー構造ができたら、 default
と index
のファイルの中身を以下の通り入力してください。推奨文字コードは UTF-8 ですが、 Catalpa には文字コードの自動認識機能がありますので Shift_JIS や EUC-JP でファイルを作成しても構いません。
default.ftl<!DOCTYPE html>
<HTML>
<HEAD>
<META charset="utf-8">
</HEAD>
<BODY>
${content}
</BODY>
</HTML>
次は index
です。これは、 Web ページに表示されるコンテンツになるので内容を多少アレンジしても構いません。
index.md本日は**晴天**なり。
所定のフォルダー構造に default
と index
を作ったら Catalpa を起動して D:¥mysite
を開きます。
フォルダーを開くと自動的に処理が始まります。正常に終了したら ブラウザーで開く を押してください。既定のブラウザーが起動して作成された Web ページが表示されます。
この Web ページの HTML は以下のようになっています。
index.html<!DOCTYPE html>
<HTML>
<HEAD>
<META charset="utf-8">
</HEAD>
<BODY>
本日は**晴天**なり。
</BODY>
</HTML>
default
の ${content}
部分が index
の中身に置き換わった形ですね。これがテンプレート処理の結果です。テンプレートを使うことで、 レイアウトやドキュメント構造を担当する HTML とコンテンツ本文を分離して別々のファイルに記述できるわけです。Web サイトの各ページ ・ レイアウトが共通であればテンプレートを使いまわせるので、 HTML を気にせず、 コンテンツ本文 (*.md
) を書くことに専念することができます。
さきほどの Web ページ表示では 「晴天」 の前後にアスタリスク (**) が表示されていたことに気付きましたか? 最初の例では index
の内容がそのまま ${content}
と置き換わっただけでした。これでは、 プレーン ・ テキストを流し込むことしかできず Web ページの表現が乏しくなってしまいます。
そこで登場するのがマークダウン処理です。default
の内容を下記の通りに書き換えてください。${content}
を <@markdown>
と </@markdown>
で囲みます。こうすることで、 index
の内容がそのまま出力されるのではなく、 マークダウン処理を施してから出力されるようになります。
default.ftl<!DOCTYPE html>
<HTML>
<HEAD>
<META charset="utf-8">
</HEAD>
<BODY>
<@markdown>${content}</@markdown>
</BODY>
</HTML>
もう一度、 Catalpa で D:¥mysite
を処理してみましょう。すでに、 Catalpa を起動している場合は 更新 を押すだけです。
ブラウザーの表示は以下のようになります。「晴天」 の前後にあったアスタリスク (**) 表示が無くなり、 代わりに 「晴天」 の文字が強調されています。
出力された HTML も確認してみましょう。index
でアスタリスク (**) で囲んでいた部分が <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 早見表で確認できます。
Markdown ファイル (.md
) の先頭には YAML front matter (フロント ・ マター) を書くことができます。YAML front matter は YAML 形式で記述可能なデータ ・ ブロックです。YAML front matter は、 ファイルの先頭行が 3 つのハイフンで始まり、 3 つのハイフンの行で終わります。
index
に YAML front matter を追加してみましょう。
index.md--- title: わたしのページ --- 本日は**晴天**なり。
先頭の 3 行が YAML front matter です。ここでは title
という名前のデータを定義して、 その値を わたしのページ
としました。(ちなみに、 データの名前は自由に決めることができます。hoge
でも大丈夫です。)
YAML front matter のデータは Markdown ファイル (.md
) や、 テンプレート ・ ファイル (.ftl
) で参照することができます。
index
で title
データを参照してみましょう。${title}
と記述することで title
データを参照することができます。
index.md--- title: わたしのページ --- 本日は**晴天**なり。 このページのタイトルは「${title}」です。
Catalpa で処理すると結果は以下のようになります。${title}
の部分が置き換わっていますね。
テンプレート ・ ファイル (.ftl
) でもデータを参照することができます。default
でも 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 ページの表示は以下のようになります。
ブラウザーのタブをよく見てみるとタイトルが表示されていることが確認できます。
すでに YAML front matter にデータを定義できることを学びました。
ところで、 タイトルや著者名など同じデータを複数の Web ページに出力したいこともありますよね? そんなとき、 それぞれの Markdown ファイル (.md
) に同じデータを繰り返し定義をしなければならないのは大変です。
Catalpa には、 すべての Markdown ファイル (.md
) やテンプレート ・ ファイル (.ftl
) から共通で参照できる設定ファイルがあります。それが config
です。
config
はデータ ・ フォルダーの直下 (D:¥mysite
) に配置します。
config.yml---
title: わたしのページ
author: 匿名太郎
---
このように、 config
には (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
は、 ユーザー定義データを記述するだけでなく、 Catalpa の動作制御にも使われます。このために、 siteurl
や upload
など Catalpa で予約されているいくつかの名前があります。
ここまでの説明では default
という名前のテンプレート ・ ファイルを使用してきました。これは、 Markdown ファイル (.md
) でテンプレート名を指定しなかった場合に適用される既定のテンプレートです。
default
以外のテンプレート ・ ファイルを用意して、 Markdown ファイル (.md
) で任意のテンプレートを指定することもできます。試しに sample1
というテンプレート ・ ファイルを templates
フォルダーの下に作成してみましょう。
中身は以下のようにします。default
とほとんど同じですが、 表示したときに区別できるように背景色を薄い青色 (background:lightblue
) にしています。
sample1.ftl<!DOCTYPE html>
<HTML>
<HEAD>
<META charset="utf-8">
</HEAD>
<BODY style="background: lightblue;">
<@markdown>${content}</@markdown>
</BODY>
</HTML>
次に index
の修正です。YAML front matter に template
という名前のデータを定義して、 その値を sample1
とします。
index.md--- template: sample1 title: わたしのページ --- 本日は**晴天**なり。 このページのタイトルは「${title}」です。
これで、 この Markdown ファイル (index
) に適用されるテンプレート ・ ファイルが sample1
になります。Web ページを表示してみましょう。
背景色が薄い青色になっているので、 テンプレート ・ ファイル sample1
が適用されていることが分かります。