カスタマイズ

Catalpa で作成するサイトは、設定ファイル・変数ファイル・スタイルシート・テンプレートでカスタマイズできます。

変数

設定ファイル（config.yml）または Markdown ファイル（.md）の先頭に YAML とよばれるデータ変数を定義することでサイトをカスタマイズできます。

config.yml はルートフォルダーだけでなく任意のフォルダーにも配置できます。config.yml の内容はそのフォルダー配下に影響します。共通の設定を定義するのに適しています。
Markdown ファイル（.md）の先頭（--- で囲まれた範囲）に定義したデータ変数の内容はそのページ（.html）のみに影響します。ページ固有の設定を定義するのに適しています。config.yml で定義されているデータ変数を Markdown ファイル（.md）で再定義することで設定を上書きできます。
Markdown ファイル（.md）の中に、 #--name-- という行を書くと変数ブロックとして扱われます。name 部分は任意の識別子です。#--name-- の場合、以降の部分が変数値、 name が変数名として扱われます。変数ブロック記述を使用する場合は、 Markdown ファイル自体のコンテンツを #--content-- として変数名 content で定義してください。
変数ファイル（先頭がアンダースコア _ で始まる .md ファイル）は、ファイル名（アンダースコアと拡張子を除いた部分）が変数名、ファイルの中身が変数値として扱われます。

変数	説明
`siteurl`	サイトの URL を指定します。サイト URL は `http://` または `https://` から始まります。末尾には `/` を含みません。末尾に `/` を含めた場合は自動的に取り除かれます。タイトルのリンク URL や `sitemap.xml`、 OGP プロパティ（`og:url`）で使用されます。
`title`	タイトルを指定します。タイトルバーに表示されます。指定された値は `<title>` タグと OGP プロパティ（`og:site_name` と `og:title`）にも設定されます。必要に応じて各ページの Markdown ファイルで上書き定義しましょう。
`title_url`	ヘッダーのサイトタイトルの URL を `siteurl` からの相対パスで指定します。通常は指定する必要はありません。サブディレクトリーのタイトルをクリックした際にトップページ以外に遷移させたい場合に使います。
`description`	サイトの説明を指定します。指定された値は `<meta name="description" content="...">` と OGP プロパティ（`og:description`）に設定されます。各ページの Markdown ファイルで上書き定義しましょう。
`copyright`	サイトの著作の年を指定します。著作の年はページの既定のフッターに表示されます。
`author`	サイトの著者名を指定します。著者名はページの既定のフッターに表示されます。指定を省略すると著者名の代わりにメールアドレスが表示されます。
`mailto`	著者のメールアドレスを指定します。既定のフッターに表示される著者名またはメールアドレスの `mailto` リンクになります。
`legal`	指定した内容が既定のフッター中央に表示されます。プライバシーポリシーや特定商取引法に基づく表記へのリンクを配置することを想定しています。
`image`	イメージファイルを `siteurl` からの相対パスで指定します。指定された値は OGP プロパティ（`og:image`）に設定されます。指定を省略すると `og:image` は出力されません。
`template`	Markdown ファイルに適用するテンプレート名を指定します。指定を省略した場合、 `default.ftl` がテンプレートとして適用されます。テンプレート名の指定では拡張子 `.ftl` を省略することもできます。テンプレートはルートフォルダーの `templates` フォルダーから検索されます。この変数を定義してもブログ記事に適用するテンプレートは変更できません。ブログ記事に適用されるテンプレートは `blog-post.ftl` に固定されています。
`robots`	robots meta タグの値を指定します。指定された値は `<meta name="description" content="...">` に設定されます。検索エンジンのインデックスに登録したくないページでは `noindex` を指定しましょう。なお、検索ページ（`search.ftl`）とブログのインデックス・ページ（`blog-index.ftl`）には `noindex` が固定で指定されています。
`theme_color`	theme-color meta タグの値を指定します。指定された値は `<meta name="theme-color" content="...">` に設定されます。この指定は Android 版 Chrome のメニューバーの色に反映されます。
`hide`	`header` , `footer` , `sns_all` , `sns_hatena` , `sns_facebook` , `sns_x` を指定できます。複数指定する場合は `+` や `,` など任意の文字を使って文字列を連結してください。`header` が指定されていると既定のヘッダーが表示されなくなります。`footer` が指定されていると既定のフッターが表示されなくなります。`sns_all` が指定されているとすべての SNS ボタンが表示されなくなります。`sns_hatena` が指定されているとはてブ SNS ボタンが表示されなくなります。`sns_facebook` が指定されていると Facebook SNS ボタンが表示されなくなります。`sns_x` が指定されていると X （旧 Twitter） SNS ボタンが表示されなくなります。
`head`	指定した内容が `<HEAD>` 開始タグの直後に出力されます。変数ファイル `_head.md` に Google Adsense の gtag を設定するような使い方が便利です。
`tail`	指定した内容が `</BODY>` 終了タグの直前に出力されます。共通の JavaScript を出力するような使い方を想定しています。
`css`	指定した内容が `<HEAD>タグ内にある<STYLE>タグの末尾に出力されます。Markdownファイル内でCSSを変更するのに役立ちます。`

自動的に定義される変数

変数	説明
`baseurl`	ベース URL が相対パスで格納されます。ルートフォルダーに配置した Markdown ファイルで `${baseurl}` を参照すると値は空文字になります。ルートフォルダーの `sub` フォルダーに配置した Markdown ファイルで `${baseurl}` を参照すると値は `../` になります。たとえば、 `${baseurl}img` はどの階層に配置された Markdown ファイルから参照してもルートフォルダーの `img` を指し示します。
`path`	ページの（ルートフォルダーを基準とした）相対パスが格納されます。この値は URL エンコードされていません。FreeMarker の組み込み機能 `?url_path` を使うことで URL エンコードされた文字列を参照できます。先頭に `/` （スラッシュ）は含まれません。`${siteurl}` と連結することでページの URL を表すことができます。`${siteurl!}/${path!?url_path}`
`url`	ページの URL が格納されます。`${siteurl!}/${path!?url_path}` と同等の値が格納されています。この値は URL エンコードされています。
`dateModified`	［非推奨］ページの最終更新日が格納されています。代わりに `contentLastModified` を使用してください。
`contentLastModified`	Markdown ファイルの最終更新日が格納されます。FreeMarker の組み込み機能 `?string` を使うことで出力書式を指定できます。たとえば、 `yyyy-MM-dd` の書式で出力する場合は `${contentLastModified?string["yyyy-MM-dd"]}` と書きます。
`_PREVIEW`	Catalpa のローカル・サーバー機能でプレビューしていることを示すフラグです。プレビュー時は `true` になります。「名前を付けて保存」または「アップロード」するときは `false` になります。

ブログ記事に定義できる変数

config.yml に type: blog を定義すると、そのフォルダー下位がブログとして扱われます。

変数	説明
`date`	記事の日付を `yyyy-mm-dd` の形式で指定します。
`title`	記事のタイトルを指定します。
`description`	記事の説明を指定します。
`categories`	記事のカテゴリーを指定します。全体を `[` と `]` で囲み、各カテゴリーを `,` で区切ります。カテゴリーに日本語を使う場合は末尾に `(...)` で半角英数字のみの表記を繋げることをおすすめします。これはカテゴリーページの URL として使用されます。たとえば、 `プログラミング(programming)` と記述すると、カテゴリー名が「プログラミング」、カテゴリーページの URL が `programming` になります。すべての記事でカテゴリー URL を明示する必要はありません。1 つの記事で `プログラミング(programming)` というカテゴリー指定がされていれば、他の記事では `プログラミング` というカテゴリー指定だけでも構いません。自動的にカテゴリー URL は `programming` になります。新しいカテゴリーを始めて使うときは `(...)` でカテゴリー URL を定義する、と覚えておくと良いと思います。
`thumbnail`	記事のサムネイル画像を記事ファイル（`.md`）からの相対パスで指定します。指定を省略した場合、 `thumbnail.(webp\|png\|jpg\|jpeg\|gif)` を検索して見つかればそれを使用します。見つからなければさらに、 `image.(webp\|png\|jpg\|jpeg\|gif)` を検索して見つかればそれを使用します。
`image`	OGP プロパティ（`og:image`）に設定される画像を記事ファイル（`.md`）からの相対パスで指定します。指定を省略した場合、 `image.(webp\|png\|jpg\|jpeg\|gif)` を検索して見つかればそれを使用します。見つからなければさらに、 `thumbnail.(webp\|png\|jpg\|jpeg\|gif)` を検索して見つかればそれを使用します。
`draft`	変数 `draft` を空値で定義すると、この記事が作成中であることを示します。作成中の記事がある場合、 Catalpa は他の記事を処理しないようになります。これは処理時間を短縮するのに効果的です。また、変数 `draft` の値を空値ではなく `skip` にすると、その記事はスキップされ Catalpa の処理対象にならなくなります。作成中の記事を保留してサイト全体を出力したい場合に `skip` が役に立ちます。

CSS

CSS ファイルでサイトをカスタマイズできます。css フォルダーに custom.css という名前のファイルを配置すると自動的に参照されます。

テンプレート（.ftl）を編集すれば任意の名前の CSS ファイルを参照するようにできますが、テンプレートの変更はあまりおすすめしていません。テンプレートの変更は HTML/CSS に慣れた上級者向けのカスタマイズになります。

css フォルダーには color.css や main.css などの CSS ファイルが含まれています。これらのファイル編集はおすすめしていません。独自のカスタマイズは custom.css でおこないましょう。Catalpa の配布物には custom.css は含まれないため、バージョンアップ時に誤って上書きしてまうことがありません。

例

css¥custom.css
:root {
	--primary-color: #287dc0; /* プライマリーカラー（ヘッダーなど）を青色にします。*/
	--main-text-color: blue; /* テキストを青色にします */
}

/* H2レベルの見出しの左側に■を表示します */
.markdown h2 {
	padding: 0.25em 0.5em;
	border-left: 0.5em solid #DEE99A;
}

色を変更するときは css¥color.css を参照して該当する CSS 変数名を探して、 custom.css に同じ CSS 変数を再定義してください。（直接、 color.css の書き替えることはおすすめしていません。）

テンプレート

templates フォルダー内のテンプレート（.ftl）を編集または追加することでサイトをカスタマイズできます。これは上級者向けのカスタマイズです。HTML/CSS だけでなく FreeMarker 構文の理解が必要です。

トップページに戻る