静的サイトジェネレーター Franklin.jl

2 Apr 2021

(src=https://pixabay.com/photos/money-benjamin-franklin-dollar-4806693/)
Franklin.jlはjulia言語で作られた静的サイト作成パッケージです。 このサイトはFranklin.jlを利用して作成しました。 技術系のブログの選択肢としては、WordPress、はてなブログ、Qiitaなど色々あります。 julia言語が好きで、juliaのコードや数式を使ったブログを書きたいけど、 まだブログサイトを持っていない私のような人にとって、Franklin.jlは悪くない選択肢だと思います。

本サイトの作成にあたって参考にしたサイトはこちらです。

使ってみる

インストール方法

まずREPLのパッケージモードからFranklinをインストールします。

julia>]
(pkg)>add Franklin

デモサイトを作ってみる。

以下のコードを実行すると、mySiteというフォルダー作成後にローカルサーバーが立ち上がり、 http://localhost:8000/にアクセスするとデモサイトを確認することができます。

using Franklin
newsite("mySite",template="vela")
serve()

テンプレートはここで確認できます。

mySiteフォルダー以下にマークダウンファイルや素材が入っています。 テンプレートファイルをいじりながら使って行くことになります。 ライブレンダリングによって編集後の結果をすぐに確認できるので、 初心者でも使いやすいと思います。 サーバー停止後にもう一度起動する時は、mySiteフォルダーでREPLを立ち上げて、

using Franklin;serve()

とタイプします。

基本的な文法

マークダウンの記法にしたがって文章を書きます。

# h1タグ
## h2タグ
### h3タグ

1. 番号付きリスト
1. 番号付きリスト
1. 番号付きリスト

- 番号なしリスト
- 番号なしリスト
- 番号なしリスト

[リンク名](リンク先)

また、Katexによる数式レンダリングを標準でサポートしています。 TeXの記法に慣れた人には、数式入力も楽々です。

$$ \int_{a}^{b} f(x) = F(b) - F(a)$$
∫abf(x)=F(b)−F(a) \int_{a}^{b} f(x) = F(b) - F(a)

juliaのコードを書いてみる。

マークダウンの中で次のようなコードを実行したとします。

```julia:test
println("Hello Franklin")
```
\show{test}

するとこのコードが実行された結果を出力できます。

println("Hello Franklin")
Hello Franklin

次のように書いてやればグラフを出力できます。

```julia:plot
using Plots
p = plot(x->sin(x),xlabel="x",ylabel="y")
savefig(p,joinpath(@OUTPUT,"figplot.svg"))
```

\figpop{figplot}
using Plots
p = plot(x->sin(x),xlabel="x",ylabel="y")
savefig(p,joinpath(@OUTPUT,"figplot.svg"))

注意したいポイント

\記号に気を付けよう

\の記号をMarkdownの中で使うときは注意が必要です。 FranklinはMarkdownのなかで拡張されたコマンドを使うことができます。 たとえば、こんな具合です。

<!-- コマンドの定義 -->
\newcommand{\bolditaliccenter}[1]{ ~~~
<div
  style="font-size:xx-large;text-align:center;font-style:italic; font-weight:bold"
>
  #1
</div>
~~~ }
<!-- コマンドの実行 -->
\bolditaliccenter{無駄!}
無駄!

Franklinは、\が付くところをコマンドだとみなすので、下手に\を使おう ものなら\newcommandで定義されていないコマンドとみなされ、 サーバーが落ちてライブレンダリングできなくなります。

通常のマークダウンを書いているときはミスをしにくいと思いますが、Literate.jlと連携してドキュメントを書いているときは、 文章がコメントアウトされてミスに気づきにくいので注意が必要です。

juliaコード内の変数のスコープ

juliaを使うときは、ループや関数内部からグローバル変数を何の断りもなく参照するのは アウトだと知っている人も多いと思います。

この罠は、REPLやjupyterを使ってプロトタイピングをしているときには気にしなくてもよいですが、powershellなどでjulia hoge.jlとするときはアウトになります。

Franklinでjuliaのコードを実行するときは、この状況になるようで、実際に試してみると

a = 1
for i in 1:2
    a += 1
end

UndefVarError: a not defined
となってしまいます。 これを防ぐには、let環境に入れ込んでしまうか、

let
a = 1
for i in 1:2
    a += 1
end
a
end
3

コントロールの中でグローバル変数であることを明記する必要があります。[1]

a = 1
for i in 1:2
    global a += 1
end
a
3
[1] global a #hideのように書けば、コードを隠すこともできます。

GitHub actions の罠

GitHub pagesを使えば、無料でホームページを作ることができます。Franklin.jlでは GitHub actions(GitHubのレポジトリの中で自動的に実行される処理)を利用して、 サイトを構成することが推奨されています。

Franklin の場合は、 .github\workflows\deploy.ymlにコードが記載されていて、 リモートレポジトリへpushしたときに処理が実行されます。 deploy.ymlの中身を見れば雰囲気がわかると思いますが、処理の流れをざっくり説明すると

  1. GitHub上でOSを立ち上げて、juliaやら何やら必要なものをインストール

  2. Franklinを実行して、サイト(__siteフォルダー以下)を作る

  3. gh-pagesブランチにできたサイトをぶちこむ ということになります。

個別の状況によりますが、このdeploy.ymlは修正する必要があります。 私がハマった点を書いておきます。

master or main?

2020年にGitHubのデフォルトブランチ名がmasterからmainに変更されました。 これに伴って、Franklinでもdeploy.ymlには、mainブランチにプッシュされると動作するようになっています。

当たり前ですが、この状態でmasterブランチにプッシュしても何も起こりません。 deploy.ymlのブランチ名を実際のブランチ名と合わせる必要があります。

gh-pages の設定をしておくこと

レポジトリのページのSettingsタブの下の方にGitHub Pages の欄があります。 ソースのブランチにgh-pagesを選択しておく必要があります。

どのレポジトリにプッシュするか

username.github.io以外のレポジトリにプッシュするときは、deploy.yml の中に書いてあるoptimize()を optimize(;prepath="レポジトリ名")にしておく必要があります。

そうしないと、リンク切れを起こしてしまいます。

Project.toml を入れておこう。

GitHub actionsでのデプロイ時には、juliaコードの中で使用したパッケージがわかるように、 教えてやる必要があります。ローカルレポジトリで、以下のように処理しておくと、

julia>]
(pkg)>activate .
(pkg)>add Plots # 使用したパッケージ

Project.toml が作成されるので、deploy.yml のなかでいちいち Pkg.add(~~)する必要はなくなります。

プロットのxylabelが切れる

localサーバー上では問題なくプロットを表示できるのですが、 gh-pagesで表示を確認すると、グラフのマージン設定を上手くできない場合があります。 以下のようなコードを書いてマージンを設定しておけば解決することができました。

using Plots.PlotMeasures
Plots.reset_defaults()
default(
    left_margin = 30px,
    bottom_margin = 30px
)

せっかくなので、拡張してみる。

htmlやcssに関する知識が多少あれば、テンプレートファイルをいじって機能を拡張[1]することが可能です。 私はadomonitionの設定、トップに戻るボタン、mermaid.jsによるフローチャート描画の機能などを追加してみました。

フォントを追加した例を書いておきます。

コードのフォントには juliamono を使おう

juliamonoフォントを使えば、juliaのコードを洗練された見栄えに変更できます。 ->が->になったり、|>が|>になるので、パイプ演算子や無名関数を多用する人は、気に入るのではないでしょうか? Cormullion のブログ(このサイトもFranklinで作られている。)にインストール方法は載っています。

cssでwebフォントとして使うのも簡単でこちらにやり方が載っています。 少し改変したものが以下になります。まず、cssファイルに

@font-face {
  font-family: JuliaMono-Regular;
  src: url("https://cdn.jsdelivr.net/gh/cormullion/juliamono/webfonts/JuliaMono-Regular.woff2");
}

と書いて、次にcssセレクターのなかで、codeを探して、

code {
  font-family: "JuliaMono-Regular", Monaco, Consolas, "Lucida Console",
    monospace;
}

などとしておけば良いです。(font-familyの一番左に書くことが重要)

まとめ

  • Franklin.jl を使えば、テンプレートサイトをいじって簡単に自分だけのサイトが作れる。

  • 自分だけのコマンドを作れるが、\の記号には注意が必要。

  • julia コードを実行するときは変数のスコープに注意する。

  • GitHub-pagesを利用して無料でホームページを作れる。

  • GitHub-pagesを使うときは、deploy.yml、Project.toml、ソースブランチの設定に注意。

  • cssやjavascriptをいじって自分で拡張できる。

めでたしめでたし