カスタマイズ
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 構文の理解が必要です。