🥰

Documenter.jlでウェブサイトを作って公開するまで

2021/09/09に公開

Julia

Web

tech

前置き

できるようになること

Julia のパッケージである Documenter.jl を使ってマークダウンからHTMLを生成し，GitHub Pagesを使って公開するまでの流れをまとめます．

私はこれを使って自分のウェブサイトを作成して公開しています．以下のリンクから良ければご覧ください．

おことわり

きっと，もっと上手なやり方があります．Twitterにて助言いただいている箇所もたくさんありますが，私ができたレベルでご紹介します．私もスキルレベルを上げて進化させていく所存です．私のスキルアップに伴ってこの記事も進化していく予定です．
普段は大学院生をしていて，プログラミングをゴリゴリ使うような研究をしているわけではありません．これは全て独学+Twitterで優しい方々から教えていただいたことを参考にまとめています．記事内の専門用語などに違和感がありましたらコメント等で教えてください．(言い訳まがいですみません)

実装の前に

実装をする前に以下を済ませておきましょう．ここで詳細な説明はしません．

Julia Language の install (参考)
GitHub へのアカウント登録

実装

ファイルとフォルダの作成

以下の階層構造を参考にして，フォルダとファイルを作成します．

terminal

user: kadowakimizuto Documenter-demo 
⚡️ 94% ➜ tree
.
├── LICENSE //レポジトリを作成した際に作ったライセンスファイル
├── README.md
└── docs
    ├── make.jl
    └── src
        └── index.md

2 directories, 4 files

index.md の作成

.md は「マークダウン」の拡張子です．ウェブサイトの内容にあたる部分はMarkdownで書いていきます．Markdown形式に馴染みがない方はこちらあたりが参考になるかもしれません．

index.md

# Documenter.jl を使ってウェブサイトを作成する

hogehoge

make.jl の作成と実行

最初に準備した make.jl に以下を記述します．

make.jl

using Documenter
makedocs(;
    sitename="Demo"
)

最低限，これで実行可能です．コードを実行してみましょう．

問題なくコードが実行されると，以下のようなメッセージが出力されると思います．

[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.

ここで，terminal上でもう一度treeを確認しましょう．

terminal

user: kadowakimizuto Documenter-demo 
⚡️ 99% ➜ tree
.
├── LICENSE
├── README.md
└── docs
    ├── build
    │   ├── assets
    │   │   ├── documenter.js
    │   │   ├── search.js
    │   │   ├── themes
    │   │   │   ├── documenter-dark.css
    │   │   │   └── documenter-light.css
    │   │   ├── themeswap.js
    │   │   └── warner.js
    │   ├── index.html
    │   ├── search
    │   │   └── index.html
    │   └── search_index.js
    ├── make.jl
    └── src
        └── index.md

6 directories, 13 files

docs内に build が生成され，index.htmlをはじめとするファイルが生成されています．ここまでたどり着くことができればOKです．

他のページを追加する方法などは後述しています．

GitHub Pagesでの公開設定

ここまで作成したファイルを GitHub に push しておきましょう．

push が済んだら Setting > Pages へと進みます．

以下の画像のように mainのdocs内にファイルがあるなあ・・・と選択してsave.

saveするとリンクが発行されます．これを開いてめでたく公開．．．

できない！

そう，何を隠そうここが私が詰まったところでした．　何が原因でしょうか．もう一度treeをみてみましょう．

terminal

user: kadowakimizuto Documenter-demo 
⚡️ 99% ➜ tree
.
├── LICENSE
├── README.md
└── docs
    ├── build
    │   ├── assets
    │   │   ├── documenter.js
    │   │   ├── search.js
    │   │   ├── themes
    │   │   │   ├── documenter-dark.css
    │   │   │   └── documenter-light.css
    │   │   ├── themeswap.js
    │   │   └── warner.js
    │   ├── index.html
    │   ├── search
    │   │   └── index.html
    │   └── search_index.js
    ├── make.jl
    └── src
        └── index.md

6 directories, 13 files

勘の良い読者なら．．．(理工系専門書にあるチクチク言葉)

そうです，表示したいindex.htmlは build内部にあります．Pagesの設定をしたときに発行されたリンクだけでは不十分だったわけですね．

それでは，先ほど発行されたリンクの最後にbuildを追加して再表示してみましょう．

すると，以下のように表示されたのではないでしょうか．

このページのリンクを貼るので，なんのこっちゃ分からない方は以下のリンク先からURLを確認してみてください．(この先で説明する内容も含んでいるためスクリーンショットの内容と異なる場合があります．)

さて，ここまでで本当に最低限の作業で公開までたどり着けました．ここまで上手く実行できた方，おめでとうございます．

より素敵なページを作成する

複数ページを追加する

下の画像をご覧いただいてもわかるように，内容別などでページを追加することができます．

以下で手順をみていきましょう．

フォルダ・ファイルの作成

以下の階層構造を参考に，src内にchapterフォルダを作成して，その中に2つのマークダウンファイルを準備しました．

terminal

user: kadowakimizuto Documenter-demo 
🔋 99% ➜ tree
.
├── LICENSE
├── README.md
└── docs
    ├── build
    │   ├── assets
    │   │   ├── documenter.js
    │   │   ├── search.js
    │   │   ├── themes
    │   │   │   ├── documenter-dark.css
    │   │   │   └── documenter-light.css
    │   │   ├── themeswap.js
    │   │   └── warner.js
    │   ├── index.html
    │   ├── search
    │   │   └── index.html
    │   └── search_index.js
    ├── make.jl
    └── src
        ├── chapter
        │   ├── 01.md
        │   └── 02.md
        └── index.md

7 directories, 15 files

新規作成したマークダウンに内容を記述してからの流れは上記と同じです．make.jlを実行して更新されたファイルをGitHubにpushして(数分おいて)リンクを更新すると変更が反映されます．ファイル数が増えてもmake.jlに書き足す内容なども特にありません．

サイドバーにページが追加されていることが確認できます．

画像を挿入する

準備

以下の階層構造を参考にchapter内にimagesフォルダと画像を用意します．また，03.mdを用意しています．

terminal

user: kadowakimizuto Documenter-demo 
🔋 99% ➜ tree
.
├── LICENSE
├── README.md
└── docs
    ├── build
    │   ├── assets
    │   │   ├── documenter.js
    │   │   ├── search.js
    │   │   ├── themes
    │   │   │   ├── documenter-dark.css
    │   │   │   └── documenter-light.css
    │   │   ├── themeswap.js
    │   │   └── warner.js
    │   ├── chapter
    │   │   ├── 01
    │   │   │   └── index.html
    │   │   └── 02
    │   │       └── index.html
    │   ├── index.html
    │   ├── search
    │   │   └── index.html
    │   └── search_index.js
    ├── make.jl
    └── src
        ├── chapter
        │   ├── 01.md
        │   ├── 02.md
        │   ├── 03.md
        │   └── images
        │       └── img.png
        └── index.md

11 directories, 19 files

マークダウンの文法で挿入する

マークダウン記法による画像の挿入は

03.md

![](画像へのパス)

です．これを指定してこれまでと同じ流れを辿ると，以下のように画像が挿入されていることが確認できます．

ここで，画像がbuildフォルダ内にも複製されていることを覚えていてください．後述するHTML形式で画像を挿入する際に必要になってきます．

└── docs
    ├── build
    │   ├── assets
    │   │   ├── documenter.js
    │   │   ├── search.js
    │   │   ├── themes
    │   │   │   ├── documenter-dark.css
    │   │   │   └── documenter-light.css
    │   │   ├── themeswap.js
    │   │   └── warner.js
    │   ├── chapter
    │   │   ├── 01
    │   │   │   └── index.html
    │   │   ├── 02
    │   │   │   └── index.html
    │   │   ├── 03
    │   │   │   └── index.html
    │   │   └── images
    │   │       └── img.png <--
    │   ├── index.html
    │   ├── search
    │   │   └── index.html
    │   └── search_index.js

HTML記法による画像の挿入

なぜマークダウン形式で画像が挿入できたのにこの方法を紹介するのか．それはサイズ指定が容易にできるためです．これに関しても私が実装したときはうまくできませんでしたが，Twitterにてごまふあざらしさん(@MathSorcerer)に丁寧に教えていただきましたので紹介させていただきます．

以下のissues

にもあるように，@raw htmlを使って指定できます．このとき，後に生成されるHTMLに読み込まれるように build内に複製される画像のパスをdocs起点で指定する必要があるそうです．

実は私のローカルではまだ上手くいっていなくて，パスの指定などを見直しているところです．皆様も上の議論を参考にローカルで上手くいったらぜひ教えてください．

追記：以下で生成される../../assets/logo.pngは問題なく表示されるようです．HTML形式で指定して表示したい画像は全部assetsに入れないとダメなのかな．

ページロゴを設定する

ページロゴは，サイト表示時に現れる画像(添付画像参照)です．

この設定方法について．公式docでは以下のように書いています．

During the build process, Documenter looks for suitable graphic images in the src/assets/ directory and automatically copies them to /build/assets/.

src/assetsに追加した画像のうち適しているものを指定するそうです．
　
というわけで，以下の階層構造のようにassetsフォルダとlogo.pngを用意します．

    └── src
        ├── assets
        │   └── logo.png

これでmake.jlを実行すると build/aseets/logo.pngが生成されていることが確認できます．そしていつものようにGitHub に pushして更新してみると無事に表示されていることが確認できます．

公開設定について

公開に関する設定については，ほりたみゅさん(@Hyrodium)に助言をいただきました．上記した方法では，GitHub Pagesの設定によって取得したURLに/buildを付け加えることで公開される，といった流れでした．

ほりたみゅさん曰く，

GitHub Actionsの設定とmake.jlで

make.jl

deploydocs(;
    devbranch="main",
    target="build",
    repo="github.com/MizutoKadowaki0312/Documenter-demo",
    versions=nothing
)

を指定することで有効になる設定があるということです．私の環境ではGitHub Actionsをいじっていないのでまだ恩恵を受けることはできていませんが，近々実装する予定です．

この周辺に関してはほりたみゅさんご本人の記事から説明が出ていますのでご確認ください．

また，make.jlのコード内容もお示しいただきました．

これらを参考に実装することで，よりスマートに公開のための準備をすることができます．

最後に

ここまで読んでいただいた皆さま，本当にありがとうございました．拙い文章ですので理解できない箇所などありましたら遠慮なくコメントをよろしくお願いいたします．

このスキルをもってやりたいこと

Documenter.jl，GitHub Pagesのおかげで簡単にウェブサイトが公開できる環境になりました．Markdownによって数式の挿入も簡単にできるので，大学や大学院でのゼミ資料の作成にも利用できます．Weave.jlと組み合わせればグラフも簡単に表示できるかもしれません．

また，研究室内部サイトなども容易に作成できると思います．私は次に研究室内部サイトを作成する予定です．

Julia言語に興味を持ったあなたへ

もしかすると，この記事(Documenter.jlの素晴らしさ)始点でJulia言語に興味を持たれた方もいらっしゃるかもしれません．

Juliaは科学的な計算から今回のようなサイト作成まで幅広いことがシンプルなコードで実装できる素敵な言語です．ぜひ触れてみてください．

謝辞

私がこのツイートをして個人サイトを完成させることができた裏には，Twitter上で分からないことや詰まった点に対して改善方法を教えてくださった優しい方々のご協力があります．できるだけ文中で紹介させていただきましたが，まだまだあると思います．本当にありがとうございました．

私もこのように記事を作成・発信する形で後学の方のお役に立てればと思います．

前置き

できるようになること

おことわり

実装の前に

実装

ファイルとフォルダの作成

index.md の作成

make.jl の作成と実行

GitHub Pagesでの公開設定

より素敵なページを作成する

複数ページを追加する

フォルダ・ファイルの作成

画像を挿入する

準備

マークダウンの文法で挿入する

HTML記法による画像の挿入

ページロゴを設定する

公開設定について

最後に

このスキルをもってやりたいこと

Julia言語に興味を持ったあなたへ

謝辞

Discussion