Zenn
🙌

Franklin.jl で github.io のページを作ろう.

2021/01/22に公開
Julia
#
franklin
tech

本日は

  • Zenn に入門しました．新しい気持ちで 2021 年を迎えるために自分の GitHub の見栄えをよくしようとしました．いわゆるぽ〜とふぉりお〜なるものですね．自分の github.io を数年前に作ってましたが放置だったので作り直そうと思いました．そういえば Franklin.jl でWebページ作れたから github.io にデプロイできるんじゃない？って考えたら一瞬だったので方法を共有します．

対象となる読者

  • プログラミング言語 Julia を知っている人
    • julia コマンドの使い方をわかる程度
  • GitHub のアカウントを持っている人
    • git push とかぐらいはできる
  • あまりウェブのことわからないけれど簡易的なページを作りたい
    • Markdown ぐらいならできる

導入

予備知識

そもそも github.io のお話

自分のアカウント名が myaccount だとしましょう. myaccount.github.io という名前のリポジトリを作ると https://myaccount.github.io/ という名前で自分のウェブサイトが作れるというサービスです．

https://pages.github.com/　先にある YouTube を観ると雰囲気がつかめます．

Franklin.jl

  • Franklin.jl 静的サイトジェネレータのひとつで，マークダウンで記述された文章を html に変換しウェブサイトを作る機能を持つ Julia のパッケージです. Julia は科学技術計算が得意なプログラミング言語ですが，こういったWebサイトを作るパッケージもあります．

どんな感じのができるの?

講義のホームページ の作成を目的に活用という事例もあります．

おしゃれですね．もちろん日本語もかけます．私のページです．

https://terasakisatoshi.github.io/MathSeminar.jl/

よっしゃ使いたい.

リポジトリを作ります

<自分のGitHubアカウント名>.github.io の名前のリポジトリを作ります．たとえば私は terasakisatoshi.github.io です. そしてクローンしておきます.

$ git clone https://github.com/<自分のGitHubアカウント名>/<自分のGitHubアカウント名>.github.io.git
$ ls
<自分のGitHubアカウント名>.github.io.git

Julia を起動します

Julia わからないけれど，どうしてもこの記事を試したいんだという人は

https://julialang.org/

JuliaLangのダウンロードページに行きバイナリーを落とした後 platform specific instructions に従ってパスなりを通してください．

Franklin.jl のインストールとお試し

ターミナルを開いて julia を起動します.

$ julia
               _
  _       _ _(_)_     |  Documentation: https://docs.julialang.org
 (_)     | (_) (_)    |
  _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
 | | | | | | |/ _` |  |
 | | |_| | | | (_| |  |  Version 1.5.3 (2020-11-09)
_/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

julia>

REPL の上で次を実行します．

julia> using Pkg; Pkg.add("Franklin")

julia> using Franklin

julia> newsite("mySite", template="vela")
✓ Website folder generated at "mySite" (now the current directory).
→ Use serve() from Franklin to see the website in your browser.

julia> pwd() # mySite にディレクトリが移動する.

julia> serve()

 Activating environment at `~/tmp/mySite/Project.toml`
→ Initial full pass...
→ evaluating code [ex3] in (menu1.md)                              → Starting the server...
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

シェルだとプロンプトを表す $ を外してコピペしなければいけないですが，Julia のREPLの上だと julia> の部分も含めて全てコピペしてもOKです．REPL側で julia> の部分を無視してくれる仕様のようです．知らんかった．．．

何にせよ http://localhost:8000 にアクセスすると下記のような図が得られます．

Franklin.jl は mySite ディレクトリ以下にある md をパースして __site という自動的に生成されるディレクトリ以下に html などを作ります. serve 関数はその __site を起点としウェブサーバーをローカルに立ててくれます．

上の REPL の操作でやったように newsite("mySite", template="vela") では template というキーワードを指定しています.

でお好きなものを選べます．各自の趣味に合わせてください．

リポジトリにコピー

一度 __site を消します．これはサイトをデプロイするときに自動的に作られるので git のバージョン管理に追加"しません". mySite 以下のファイルを先ほどクローンした <自分のGitHubアカウント名>.github.io.git ディレクトリ以下に全てコピーします．このとき .github というディレクトリや .gitignore もコピーしておきます. tree コマンドを使って下記のようになっているかを確認します．

$ cd path/to/<自分のGitHubアカウント名>.github.io.git
$ tree -a -L 2
.
├── .git
│   ├── COMMIT_EDITMSG
│   ├── HEAD
│   ├── config
│   ├── description
│   ├── hooks
│   ├── index
│   ├── info
│   ├── logs
│   ├── objects
│   └── refs
├── .github
│   └── workflows
├── .gitignore
├── 404.md
├── Manifest.toml
├── Project.toml
├── _assets
│   ├── favicon.png
│   ├── hamburger.svg
│   ├── rndimg.jpg
│   └── scripts
├── _css
│   ├── franklin.css
│   └── vela.css
├── _layout
│   ├── foot.html
│   ├── foot_highlight.html
│   ├── foot_katex.html
│   ├── head.html
│   ├── head_highlight.html
│   ├── head_katex.html
│   ├── nav.html
│   ├── page_foot.html
│   ├── style.html
│   └── tag.html
├── _libs
│   ├── highlight
│   ├── katex
│   └── vela
├── config.md
├── index.md
├── menu1.md
├── menu2.md
├── menu3.md
└── utils.jl

先ほども触れましたが .github 以下に Deploy.yml があることに注意します．

$ tree .github/
.github/
└── workflows
    └── Deploy.yml

こんにちのシステムは GitHub Actions を使うことによってホームページのビルド・デプロイが容易になっています．.github/workflow/Deploy.yml をつかしておくことで GitHub にプッシュしたときにそれがトリガーとなってホームページのビルド・デプロイが自動的に行われます．ですので我々は md ファイルを編集・コミット・プッシュをひたすら行えば良いわけです．

ファイルを push

上記でコピーしたファイルを全部ステージに追加してコミットメッセージを作成してリモートリポジトリにプッシュします．

$ git add -A && git commit -am "initial files"
$ git push

たとえば，私の GitHub では次のようになりました．

しばらく時間を経過してから

https://<自分のGitHubアカウント名>.github.io/ にアクセスします．

私の場合だと https://terasakisatoshi.github.io/ です．
とりあえず，何かページが表示されればOKです．ただ @ のようなマークがそのまま出ているのが気になると思います．

最後の仕上げ

このままだと見た目が汚いです．これは GitHub が認識するブランチが master（またはmain) ブランチになっているからです．一方で Franklin が提供している GitHub Actions のスクリプト .github/workflow/Deploy.ymlは gh-pages ブランチをGitHub (GitHub Pages) 側が認識することを前提として作られています．そこで我々は最後の仕上げをすることになります．下図の一番右側にある Settings に進みます．

GitHub Pages の項目に進み Source と書かれているところを master(または main) の部分を gh-pages に変更します．

これでもうOKです．

拡張の方法

あとは各自でマークダウンを追加・編集しましょう．_layout/nav.html の中身をいじる事でページの階層を定義することができます．

_layout/nav.html
<div class="main-nav" id="menu">
  <div class="flex-container">
    <span class="sidebar-brand">
      <h3 style='font-size: 25px'>Vela Template</h3>
    </span>
  </div> <!-- class="flex-container" -->

  <nav class="sidebar-nav">
    <ul class="metismenu"  id="metismenu" >
      <li><a href="/index.html">Home</a></li>
      <li><a href="/menu1/">Code blocks</a></li>
      <li><a href="" class="has-arrow">Topic</a>
        <ul>
          <li><a href="/menu2/">More goodies</a></li>
        </ul>
      </li>
      <li><a href="/menu3/">Tags</a></li>
    </ul>
  </nav>
</div> <!-- main nav menu -->

<main id="panel">
  <div class="toggle-button hamburger hamburger--spin">
    <div class="hamburger-box">
      <div class="hamburger-inner"></div>
    </div>
  </div>
  <h1 class="page title">{{isdef title}}{{fill title}}{{end}}</h1>
  <hr>

テーマを変えたい

  • たとえば vela にしてたけれど tufte にしたかった場合は newsite("yetAnother", template="tufte") のようにして一時的なテンプレートを作成します．その中にある _layout, _css, _assets, _libs を丸々差し替えます．

tufte にするとこのようにできます．

以上です.

GitHubで編集を提案

Discussion