Catalpaについて
2021-02-28 種々雑多 Web制作

Catalpaロゴ

https://catalpa.oss.onl/

Catalpa HIRUKAWA Ryo 氏が開発した静的サイトジェネレーター。

Catalpa 日本語サイトの構築に適した静的サイトジェネレーターです 日本語組版処理 の機能が組み込まれており 和文 欧文混在の文章を綺麗にレイアウトすることができます。アプリケーションの実行には 64 ビット Windows が必要です。

中略

また 既存の静的サイトジェネレーターはコマンドラインで操作するものや プログラミング言語の開発環境やパッケージシステムを使って環境を構築するものが多く プログラミング経験のない人にとっては導入が難しいのではないかと感じました。

そこで Catalpa では ZIP ファイルを展開するだけで使い始められる GUI で操作できる といった静的サイトジェネレーター導入の敷居を下げることにもこだわりました。

中略

HTML CSS を書かなくても Markdown だけでウェブページを作成できる これが Catalpa の基本的なコンセプトです。といっても HTML CSS の使用が制限されているわけではないので 上級者は HTML CSS を直接書いてウェブページのレイアウトや装飾を細かく調整することもできます

https://catalpa.oss.onl/

Catalpa

このように はてなブログ  はてな記法モード Markdown モード ようにブログを書ける日本語静的サイトジェネレーターが Catalpa です。

メモ
当サイトは Catalpa のサンプルテンプレートと既存の Bootstrap3 で作ったページを組み合わせて運用しています。
Catalpa 以外に使用している主なオープンソースは次のとおり。

サンプルテンプレート

catalpa-0.8.x¥samples¥blog フォルダーにあるブログサイト用サンプルテンプレートのカスタマイズ方法について。

フォルダー構成の変更

blog のフォルダー構成はデフォルトでは次のようになっています。

  • blog
    • 2018
    • 2019
    • css
    • fonts
    • img
    • lib
    • templates
    • config.yml

このうち ルートフォルダーに templates フォルダーがあるというフォルダー構成だけは変えることができません。

また 2018 2019 のフォルダーは 作成した記事を年月日 yyyy¥mm¥dd¥ で分類したフォルダーなので このフォルダー構成も変えることができません。

フォルダー構成を変えることができるのは css fonts img lib 4 つだけです。フォルダー構成を変えるには テンプレートファイルのパスを次のように書き換える必要があります。ここでは assets フォルダーにまとめることとします。

category.ftl, draft.ftl, page.ftl, post.ftl, search.ftl
<link rel="stylesheet" href="${baseurl}assets/css/main.css">
<link rel="stylesheet" href="${baseurl}assets/lib/jsOnlyLightbox/css/lightbox.min.css">
(中略)
<script src="${baseurl}assets/lib/jsOnlyLightbox/js/lightbox.min.js"></script>
メモ
img のパスは多いので省略します。テキストエディターの検索 置換機能を活用してみてください。
フォルダー構成変更後
  • blog
    • 2018
    • 2019
    • assets
      • css
      • fonts
      • img
      • lib
    • templates
    • config.yml
注意点
fonts フォルダーを css とは別の階層に配置した場合 css¥include¥material-icons.less の相対パスを書き換える必要があります。

これでフォルダー構成がスッキリしましたね。

メモ
favicon.ico の配置も変更することができます デフォルトではルートフォルダーです

CSS フォルダの中身

サンプルテンプレートをカスタマイズする前に CSS フォルダの中身を把握しておきましょう。

main.less

2~13 行目 LESS の変数

LESS の変数でサンプルテンプレートの色を指定しています。
詳しくは次の main.less のカスタマイズ をご覧ください。

15~19 行目 LESS の変数 サイズ

LESS の変数でサンプルテンプレートのサイズを指定しています。
詳しくは次の main.less のカスタマイズ をご覧ください。

21~25 行目 LESS の変数 フォント

LESS の変数でサンプルテンプレートのフォントを指定しています。

27~70 行目 初期化

html body hr div a タグを初期化しています。

72~95 行目 初期化 フォント

フォントのクラスを初期化しています。

97~108 行目 インポート

include フォルダにある他の LESS ファイルをインポートしています。

110~121 行目 広告表示

Catalpa 公式サイトの広告表示用 CSS です。

include/admonition.less

admonition は警告という意味です。
Markdown 記法の付箋 CSS がまとめられています。

include/blog.less

ブログサイト用の CSS です。

1~9 行目 調整用 CSS

ブログサイトの表示を調整するための CSS です。

12~38 行目 (sidebar) categories

サイドバー sidebar.ftl のカテゴリー用の CSS です。

40~76 行目 (sidebar) recent-posts

サイドバー sidebar.ftl の最新記事用の CSS です。

78~138 行目 (main) page

トップページ page.ftl 用の CSS です。

140~168 行目 (main) post

記事 post.ftl 用の CSS です。

170~177 行目 SNS

記事に表示される SNS シェアボタンを囲む この記事を共有しませんか? と書かれている枠の CSS です。

179~191 行目 レスポンシブ対応

レスポンシブ対応用のメディアクエリです。
サンプルテンプレートのブレイクポイント スマホ用とパソコン用の表示を切り替える境界線 480px になっています。

include/button.less

ボタン用の CSS です。

1~89 行目 pager

ページャーボタン用の CSS です。

91~119 行目 default button

デフォルトボタン用の CSS です。

122~167 行目 SNS share button

SNS シェアボタンの CSS です。
アイコン画像は BASE64 エンコードで CSS に埋め込まれています。

169~194 行目 banner button

バナーボタン用の CSS です。

include/heading.less

Markdown 記法の見出し CSS がまとめられています。

include/highlight.less

Markdown 記法のコード ブロック CSS がまとめられています。

include/layout.less

レイアウト用の CSS です。

1~27 行目 body

メインとサイドバーの 2 カラムレイアウト用の CSS です。

28~79 行目 div.header

ヘッダー用の CSS です。

80~94 行目 div.flex-container

フレックスコンテナー用の CSS です。

96~104 行目 footer

フッター用の CSS です。

106~114 行目 文字寄せ

センタリング 右寄せ 左寄せ用の CSS です。
Markdown 記法のテーブル参照。

116~428 行目 Bootstrap like margin and padding

Catalpa 公式サイトのダウンロードボタンなどで使われているクラスです。

include/markdown.less

Markdown 記法 CSS がまとめられています。

1~19 行目 flex

調査中。

21~29 行目 hr

Markdown 記法の水平線 CSS がまとめられています。

31~57 行目 IMG

Markdown 記法の画像 CSS がまとめられています。

59~64 行目 P

Markdown 記法の改行 CSS がまとめられています。

66~71 行目 DL

Markdown 記法の定義リスト CSS がまとめられています。

73~78 行目 UL

Markdown 記法の箇条書きリスト CSS がまとめられています。

80~85 行目 OL

Markdown 記法の番号付きリスト CSS がまとめられています。

87~96 行目 LI

Markdown 記法のリスト CSS がまとめられています。

98~133 行目 task-list

Markdown 記法のタスク リスト CSS がまとめられています。

135~181 行目 UL .tree

ツリーリスト用 CSS がまとめられています。
Catalpa 公式サイトの簡単なサイトを作ってみる参照。

183~226 行目 TABLE

Markdown 記法のテーブル CSS がまとめられています。

228~248 行目 BLOCKQUOTE

Markdown 記法の引用 CSS がまとめられています。

250~257 行目 TT

Markdown 記法の文字装飾 CSS がまとめられています。

259~274 行目 CODE

Markdown 記法の文字装飾 CSS がまとめられています。

277~295 行目 KBD

Markdown 記法の文字装飾 CSS がまとめられています。

298~315 行目 SAMP

Markdown 記法の文字装飾 CSS がまとめられています。

include/material-color.less

調査中。

include/material-icons.less

調査中。

include/responsive.less

調査中。

include/search.less

調査中。

include/sidebar.less

調査中。

main.less のカスタマイズ

LESS の変数でサンプルテンプレートの色やサイズをカスタマイズすることができます。

@primary-color:            #3e4750;
@primary-variant-color:    #000000;
@secondary-color:          #3667d5;
@secondary-variant-color:  #2573b8;
@background-color:         #FFFFFF;
@background-variant-color: #F8F8F8;
@text-color:               #303030;
@text-variant-color:       #F8F8F8;
@text-link-color:          #2573b8;
@text-visited-link-color:  #2573b8;
@text-hover-link-color:    #eb7a3d;
@border-color:             #C0C0C0;

@primary-color 標準値 #3e4750

第一の色を指定します。

heading.less
  • .markdown h1 { color }
  • .markdown h2 { background-color }
  • .markdown h3 { border-left }
  • .markdown h4 { border-bottom }
layout.less
  • div.header-title { background-color }
  • div.header-menu > ul > li > a { color }
  • div.header-menu > ul > li > a:hover { background-color }

@primary-variant-color 標準値 #000000

異なる第一の色を指定します。標準では未使用の変数です。

@secondary-color 標準値 #3667d5

第二の色を指定します。

button.less
  • ul.pager > li > a { background-color }
  • a.banner { background-color }
material-icons.less
  • a.download-button { background-color }

@secondary-variant-color 標準値 #2573b8

異なる第二の色を指定します。

markdown.less
  • .markdown li.task-list-item input.task-list-item-checkbox:checked::before { color }

@background-color 標準値 #FFFFFF

背景色を指定します。

main.less
  • div.header-fixed-ad { background-color }
layout.less
  • div.header-menu when (@header-menu-height > 0) { background-color }
  • div.flex-container > div.flex-item-right { background-color }
markdown.less
  • .markdown ul.tree ul li:last-child:before { background }

@background-variant-color 標準値 #F8F8F8

異なる背景色を指定します。

layout.less
  • div.flex-container > div.flex-item-left { background-color }
markdown.less
  • .markdown table > tbody > tr:nth-of-type(odd) { background-color }
sidebar.less
  • div.sidebar > .sidebar-fixed-top { background-color }

@text-color 標準値 #303030

文字色を指定します。ただし<body>ではこの変数を使用していません。

button.less
  • .default-button, .default-button:hover, .default-button:visited { color }

@text-variant-color 標準値 #F8F8F8

異なる文字色を指定します。

button.less
  • ul.pager > li > a { color }
  • a.banner, a.banner:hover, a.banner:visited { color }
heading.less
  • .markdown h2 { color }
layout.less
  • div.header-title { color }
  • div.header-title a { color }
  • div.header-menu > ul > li > a:hover { color }
material-icons.less
  • a.download-button, a.download-button:hover, a.download-button:visited { color }

@text-link-color 標準値 #2573b8

未訪問リンクの色を指定します。

@text-visited-link-color 標準値 #2573b8

訪問済リンクの色を指定します。標準値は未訪問リンクと同じ色です。

@text-hover-link-color 標準値 #eb7a3d

リンクにマウスカーソルを重ねたときの色を指定します。

@border-color 標準値 #C0C0C0

境界線の色を指定します。

main.less
  • hr { border-top }
layout.less
  • div.header-menu when (@header-menu-height > 0) { border-bottom }
  • div.header-menu > ul > li { border-right }
markdown.less
  • .markdown hr { border-top }
  • .markdown table > thead > tr > th { border-bottom }
  • .markdown table > tbody > tr > td { border-top border-bottom }

サイズ

@sidebar-width: 300px;
@content-width: 728px;
@header-title-height: 40px;
@header-menu-height:  20px;
@header-fixed-ad-height: 0px;

@sidebar-width 標準値 300px

サイドバーの幅を変えることができます。

@content-width 標準値 728px

コンテンツの幅を変えることができます。

@header-title-height 標準値 40px

ヘッダーのタイトルの高さを変えることができます。

@header-menu-height 標準値 20px

ヘッダーのメニューの高さを変えることができます。なおブログサイト用サンプルテンプレートにはヘッダーのメニューがありません。

@header-fixed-ad-height 標準値 0px

ヘッダーとコンテンツの間に表示される広告の高さを変えることができます。標準でオフになっています。

Tips

半角記号が文字化けする

Markdown 記法や変数で使われている半角記号 { } など が記事中で文字化けする場合は数値文字参照に置き換えてください。

テーブルのセル幅を指定したい

HTML では<table>内に<colgroup>などを記述することでセル幅を指定することができますが Markdown 記法ではそれができないので CSS 擬似クラスを使います。

記事中のどこかに次のコードを追加してください。

<style>td:nth-child( A ) { width: B em !important; }</style>

Aは幅を指定したいセル番号 Bはセル幅の文字数を入れてください。

もしもページ内に複数のテーブルがあり それぞれ別々に指定したい場合には テーブルに {id="◯◯◯◯"} ID を割り当て 次のようにコードを書き換えてください。

<style>#◯◯◯◯ td:nth-child( A ) { width: B em !important; }</style>

トラブルシューティング

Markdown ファイルのコード内に ${baseurl} を書きたいが ../../../ と表示され 数値文字参照に置き換えてもそのまま表示される

開発者の HIRUKAWA Ryo 氏から Twitter で回答があり 2021 3 9 日に解決済みです。

${r"${baseurl}"} を試してみてください🐣

${r"そのまま出したい文字列"} は変数展開せずに出力する FreeMarker テンプレートエンジンの機能です🐥

https://twitter.com/Hirukawa_Ryo/status/1369081479884537859

Markdown ファイルに <!--more--> がなくてもトップページに 続きを読む… ボタンが表示される

開発者の HIRUKAWA Ryo 氏から Twitter で回答があり 2021 3 7 日に解決済みです。

そうですね🐣
<!--more-->を書かなかったら 続きを読む が表示されないように仕様を変更しようと思います🐥
続きがなくても<!--more-->を書いておけばボタンが表示されるようにしておけばどちらにも対応できますし🐤

https://twitter.com/Hirukawa_Ryo/status/1368097205098143747

2021-03-07 バージョン 0.8.4 リリース
ブログ形式の場合に記事中の <!--more--> の有無で 続きを読む を表示するかどうかを制御できるようにしました。

https://catalpa.oss.onl/

Markdown ファイルで <img> タグに Bootstrap のスタイルクラス .img-circle が付与されない

開発者の HIRUKAWA Ryo 氏から Twitter で回答があり 2021 2 28 日に解決済みです。

![ ](∗.png) の後にスペースを置かずに{.img-circle} を書くと img タグにスタイルクラスが付与されると思います🐣

スペースがあると img の親である p への指定と解釈されます🐥

https://twitter.com/Hirukawa_Ryo/status/1365947636696510466

![ ](*.png){.img-circle}

Markdown ファイルで文字装飾 ∗∗ が機能しない

開発者の HIRUKAWA Ryo 氏から Twitter で回答があり 2021 2 28 日に解決済みです。

Catalpa の文字装飾 ∗∗ が機能しない理由が分かりました🐣

使用している Markdown プロセッサーライブラリ flexmark の仕様のようです。VScode 等のエディタでも同様の振る舞いをしているのでバグではなく仕様のようです。

強調範囲の開始または終了が区切り文字だと装飾されないようです。回避策に続く…

https://twitter.com/Hirukawa_Ryo/status/1365842020523155458

強調が開き括弧類等の文字で開始される場合は ∗∗ の前に半角スペースを入れることで回避できます。

今日は␣∗∗ 晴れ∗∗です。

半角スペースを ␣ で可視化して示しています。後工程の組版処理で調整されるので半角スペースをいれても余白ができることはありません。

https://twitter.com/Hirukawa_Ryo/status/1365842136227188736

強調が終わり括弧類や句読点の文字で終わる場合は ∗∗ の後に半角スペースを入れることで回避できます。

今日は∗∗晴れ ∗∗␣です。

https://twitter.com/Hirukawa_Ryo/status/1365842303164682244

強調が感嘆符 疑問符で終わる場合も ∗∗ の後ろに半角スペースを入れることで回避できるのですが 感嘆符 疑問符の場合は余白が入ってしまいます。

今日は∗∗晴れ!∗∗␣です。

https://twitter.com/Hirukawa_Ryo/status/1365842455543881730

半角スペースの代わりにゼロ幅スペース &#8203; や <wbr> など表示に影響しない文字やタグを挟むことによって余白を入れずに問題を回避できます。

今日は∗∗晴れ!∗∗&#8203;です。

今日は∗∗晴れ!∗∗<wbr>です。

https://twitter.com/Hirukawa_Ryo/status/1365842524787539971

萌尽狼さんのコンテンツだと一文を強調して句点で終わるケースが多いようですので 閉じる ∗∗ の後に半角スペースを入れるか 改行するかでほぼ解決できると思います😀

https://twitter.com/Hirukawa_Ryo/status/1365845743529984001

メモ
  • ∗∗ の後に <wbr> を入れるクセをつけたほうが覚えやすいし もし後で問題が起こっても検索しやすそうです。
  • 強調が終わり括弧類や句読点の文字で終わり 上記の方法でも文字装飾 ∗∗ が機能しない場合は 括弧の内側を強調するしか回避策はないようです。
    今日は ∗∗晴れ∗∗ です。

Markdown ファイルで <!--more--> より前に設置した <audio> タグがトップページで MP3 をロードできない

開発者の HIRUKAWA Ryo 氏から Twitter メールで回答があり 2021 2 25 日に解決済みです。

記事冒頭でも${baseurl}が展開されるように修正したバージョン 0.8.3 をリリースしました🐣
メールに詳細を書きましたのでご確認ください🐥

https://twitter.com/Hirukawa_Ryo/status/1364708981344673793

2021-02-23 バージョン 0.8.3 リリース
<@markdown>ディレクティブ内でテンプレート変数の展開を適用するようにしました。
トップページやカテゴリーページにブログ記事の冒頭が組み込まれる際に ${baseurl} や ${siteurl} が展開されるようになります。

https://catalpa.oss.onl/

Markdown ファイルに変数 draft を定義したらその記事がスキップ処理されてしまった

開発者の HIRUKAWA Ryo 氏から Twitter で回答があり 2021 2 24 日に解決済みです。

コロン必要です🐣
コロンを省略したときは draft キーワードとは関係なく構文エラーでその .md が処理対象から外れたのかもしれません🐥

https://twitter.com/Hirukawa_Ryo/status/1364351645111386115

下書きテンプレート draft.ftl の使い方がわからない

開発者の HIRUKAWA Ryo 氏から Twitter で回答があり 2021 2 24 日に解決済みです。

10 記事あったときに 1 記事に draft: 値なし を指定するとその 1 記事だけが処理されます。執筆中の最新記事を頻繁に確認するのに便利です🐣
このとき使われるのが draft.ftl です🐥

https://twitter.com/Hirukawa_Ryo/status/1364339864611684354

10 記事中の 1 記事に draft: skip を指定するとその記事はスキップされ残りの 9 記事のみで通常処理されます。執筆中の記事があるけど それを保留して古い記事の誤字等を直してアップロードしたいときに便利です🐣

draft: 値なし
draft: skip
で動作が違います🐥

https://twitter.com/Hirukawa_Ryo/status/1364340405379104768

この記事を共有しませんか?