カスタマイズ

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

変数

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

変数     説明
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 は出力されません。
templateMarkdown ファイルに適用するテンプレート名を指定します。指定を省略した場合 default.ftl がテンプレートとして適用されます。テンプレート名の指定では拡張子 .ftl を省略することもできます。テンプレートはルートフォルダーの templates フォルダーから検索されます。この変数を定義してもブログ記事に適用するテンプレートは変更できません。ブログ記事に適用されるテンプレートは blog-post.ftl に固定されています。
robotsrobots meta タグの値を指定します。指定された値は <meta name="description" content="..."> に設定されます。検索エンジンのインデックスに登録したくないページでは noindex を指定しましょう。なお 検索ページ search.ftl とブログのインデックス ページ blog-index.ftl には noindex が固定で指定されています。
theme_colortheme-color meta タグの値を指定します。指定された値は <meta name="theme-color" content="..."> に設定されます。この指定は Android Chrome のメニューバーの色に反映されます。
hideheader , 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 を使用してください。
contentLastModifiedMarkdown ファイルの最終更新日が格納されます。FreeMarker の組み込み機能 ?string を使うことで出力書式を指定できます。たとえば yyyy-MM-dd の書式で出力する場合は ${contentLastModified?string["yyyy-MM-dd"]} と書きます 
_PREVIEWCatalpa のローカル サーバー機能でプレビューしていることを示すフラグです。プレビュー時は 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) を検索して見つかればそれを使用します。
imageOGP プロパティ 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 構文の理解が必要です。