Parsely.jl

Parsley.jl に関して

このページは Parsley.jl のランディングページである.Parsley.jl は PkgPage.jl の使い方を学ぶために作成されました. そのため Julia の機能を提供することを目的としているわけではありません.

Parsley は日本語ではパセリという名前です. 美味しいカツサンドに付属している緑色のオブジェクトです. 私は金欠のためみなさまからの美味しい料理が掲載されたパセリの写真に関する貢献(Issue に適切なコンテンツ・サイズの画像を投稿するなど)をお待ちしております.

このページの更新日は下記の通りです:

using Dates
println("更新日 $(today())")

更新日 2023-02-19

はじめよう(ローカル環境で動作確認)

読者はすでにプログラミング言語 Julia を導入したと仮定します. PkgPage.jl を使うには Julia バージョンは 1.3 以上を要請します. とはいえ 2023 年 2 月現在では Julia の 1.6 が LTS, Julia は 1.8 が安定版です. 普段使いは 1.8 またはそれ以上のバージョンを使うと良いでしょう.

Parsley.jl の構築を真似したい場合は Parsley.jl パッケージ直下に移動します. 直下というのは ls コマンドを実行した際に README.md が見えているディレクトリに移動しているという意味です.

$ cd Parsley.jl
$ ls
Dockerfile         docker-compose.yml
LICENSE            docs
Makefile           page
Manifest.toml      src
Project.toml       test
README.md

julia コマンドで Julia の REPL を起動しましょう:

$ julia
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.8.5 (2023-01-08)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

julia>

PkgPage.jl のインストールは次のようにする(この作業は初回にすれば良い):

julia> using Pkg; Pkg.activate(); Pkg.add("PkgPage")

一度インストールしたら using PkgPage; serve() によってローカル環境でWebサーバを起動し閲覧することができる.

julia> using PkgPage; serve()
  Activating project at `~/work/Parsley.jl/page`
→ Initial full pass...
→ evaluating code [ex] in (index.md)               → Starting the server...
[ Info: Listening on: 127.0.0.1:8000, thread id: 1
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

http://localhost:8000/ に行くと結果を確認することができる.

serve 関数は page/index.md を解析し HTML に変換した結果を提供する. tree コマンドがあれば page ディレクトリの構造がわかる:

tree page -d -L 2
page
├── __site
│   ├── assets
│   ├── css
│   └── libs
├── _assets
├── _css
├── _layout
└── _libs
    ├── highlight
    └── katex

11 directories

この page の作り方は次のセクションで解説する.

Commands

• Sections

• Figures

• Tables

• Columns

• Maths

• Misc

Sections: you can indicate a section as follows:

\begin{section}{opts...}
text
\end{section}

where the available options are:

• title="..." to add a heading to the section, this should be provided,

• name="..." to add a specific name that will appear in the navbar (if not given, it will use the given title).

• width=8 an integer number controlling the width of the section with respect to the body, increase it to get a wider section.

Figures: you can indicate a figure as follows:

\figure{path="...", opts...}

where path is a valid path to the image (e.g. /assets/image.png) and the other available options are:

• width="..." to specify the width of the image (e.g. 100%),

• alt="..." to specify the image alt,

• caption="..." to specify the figure caption if any,

• style="..." to add any specific CSS styling to the image (e.g. border-radius:5px).

Tables: you can insert a table as follows:

\begin{table}{opts...}
| Column One | Column Two | Column Three |
|----------: | ---------- |:------------:|
| Row `1`    | Column `2` |              |
| *Row* 2    | **Row** 2  | Column ``3`` |
\end{table}

where the available options are:

• caption="...": to add a caption to the table,

• class="...": to add specific bootstrap classes to the table (e.g. table-striped),

• style="...": for any further styling.

Columns: you can declare an environment with columns with:

\begin{columns}
\begin{column}{}
...
\end{column}
\begin{column}{}
...
\end{column}
\end{columns}

For instance you can use this to produce:

Maths

Just use $$ ... $$ for display math and $ ... $ for inline maths:

where $P_n$ is the $n$-th Legendre polynomial and $x_i$ is it's $i$-th root.

Misc

• you can use \\ to add some vertical space (skip a line)

• you can use \begin{center}...\end{center} to center some content

• you can use \style{css}{content} to get css-styled text for instance \style{color:red;text-transform:uppercase;}{hello} gives hello

• you can use \alert{...} to draw attention to some text via a coloured box.

You can also define your own commands which can be as complex as you might want, see the Franklin docs for more information.

Deployment

By following these instructions, the content of the rendered website will be copied to a gh-pages branch where it will be deployed by GitHub. If you would like to deploy the page with your own URL or using something else than GitHub, have a look at the specific instructions further on.

Adjust DeployPage: start by checking the .github/workflows/DeployPage.yml in particular:

• if you want to use Python or matplotlib, uncomment the relevant lines

• in the run block ensure that

  • NodeJS and PkgPage are added,

  • any packages that your page might rely on are added,

  • the optimize call has the appropriate input and output path (if you're in the default setting, leave as is).

GitIgnore: it's important you specify that page/__site should be ignored by git and not pushed to your repository otherwise the build process might not work properly. To do so create a file .gitignore containing the line

page/__site

as shown here.

GitAttributes: in order for GitHub to ignore page folder it the language statistics for your repository, make sure to add a file .gitattributes with content

page/* linguist-vendored

like this.

Now whenever you push changes to the master branch of your package, the build process will be triggered and your page updated and deployed. That's it.

Avoiding clashes with Documenter.jl: if you already use Documenter.jl you might want your page to be deployed in a specific folder of gh-pages as Documenter also generates files in gh-pages.

you can do so in two steps:

1. change the run part of DeployPage.yml by specifying the output keyword argument in PkgPage.optimize for instance: PkgPage.optimize(input="page", output="page"),

2. change the prepath in config.md to reflect that the base URL will contain that additional folder, for instance @def prepath = "YourPackage.jl/page".

Use your own URL: you can usually get host services like Netlify to deploy a specific branch of a GitHub repo, do make sure to set @def prepath = "" in your config.md though.

If you want to do the deployment without GitHub actions then you will need to:

• ensure you have purgecss and highlights installed and available to NodeJS, the simplest way to do this is to install them via NodeJS with

using NodeJS;
run(`$(npm_cmd()) install highlight.js`);
run(`$(npm_cmd()) install purgecss`);

• run PkgPage.optimize(input="page", output="") (adapting input as required)

• place the content of page/__site wherever your server requires it.