静的サむトゞェネレヌタヌ 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をいじっお自分で拡匵できる。

めでたしめでたし