# Typst プロジェクト

プロジェクトごとに Typst のバージョンを固定し、Typst Universe のパッケージを追加し、フォント、ビルドバリアント、再現可能な PDF を管理し、LaTeX プロジェクトを Typst に変換します。

Oleafly には Typst 0.15.1 と Tinymist 0.15.8 の言語サーバーが付属しているので、新しい Typst プロジェクトは、何もインストールしなくてもコンパイルできます。このページでは、変更できることを説明します。プロジェクトが使う Typst、パッケージとフォントの入手元、1 つのソースから複数の PDF を作る方法です。構文とツールバーについては、まず [Typst で書く](/docs/writing/typst/)を読んでください。

## Typst のバージョン

**設定 → エンジン → Typst** を開きます。最初のカードは **Typst（組み込み）** で、アプリに同梱されているバージョンです。すでに `typst` が、お使いのコンピュータの `PATH` 上、Homebrew のフォルダ、`~/.cargo/bin` のいずれかにインストールされている場合は、2 枚目のカードに **このコンピュータの Typst** として表示されます。ちょうどそのバージョンを固定しているプロジェクトは、それを使ってコンパイルできます。

その下の **バージョン** には、Typst 0.11 から 0.15 までが新しい順に並びます。各行には、リリース日、ダウンロードサイズ、そのコピーの入手元（**組み込み**、**ダウンロード済み**、**システム**）が表示され、インストール後は、使用する Tinymist のリリースも表示されます。

- **インストール**は、そのバージョンをダウンロードします。Oleafly はまず自前のミラーを、次に GitHub を試し、アーカイブとその中のプログラムを、アプリに組み込まれた SHA-256 チェックサムと照合します。一致しないファイルは破棄され、失敗またはキャンセルされたインストールは何も残しません。ダウンロードは `~/.oleafly/toolchains/typst/` に置かれます。
- インストール済みの行の左にある丸いボタンは、そのバージョンを既定にします。
- **削除**は、ダウンロードしたバージョンを削除します。既定のバージョンは削除できないので、先に別のバージョンを既定にしてください。

### 既定のバージョンとプロジェクトの固定

新しい Typst プロジェクトは、既定のバージョンを固定します。テンプレートから作ったプロジェクト、読み込んだプロジェクト、リンクしたフォルダも同じです。固定は、パスではなくバージョン番号として、プロジェクトの `project.json` に保存されます。そのため、プロジェクトを移動したり、別のコンピュータで開いたりしても有効です。

あとから既定のバージョンを変えても、既存のプロジェクトは移りません。これは意図的な仕様です。固定された論文は、Oleafly がより新しい Typst を出荷しても、改行とページ数が変わりません。

1 つのプロジェクトのバージョンを変えるには、**再コンパイル**の横の矢印を開き、**Typst のバージョン（このプロジェクト）** を見ます。**既定**は設定で選んだバージョンに従い、固定を解除します。ほかの項目は、このコンピュータにインストールされているバージョンで、該当する場合は **[組み込み]** や **[システム]** と表示されます。一覧にないバージョンを使うには、先に設定からインストールしてください。

### 固定したバージョンが見つからないとき

このコンピュータにないバージョンを固定したプロジェクトを開いたとき、Oleafly は別の Typst で黙ってビルドすることはしません。コンパイルは「Typst 0.13.1 がインストールされていません」で止まり、プレビューには 2 つのボタンが表示されます。

- **Typst 0.13.1 をダウンロード**は、固定されたバージョンをインストールして、もう一度コンパイルします。Oleafly が提供しているバージョンの場合に表示されます。
- **Typst 0.15.1 を使う**は、既定のバージョンの名前が付いたボタンで、固定を解除して、既定のバージョンでもう一度コンパイルします。

どちらかを選ぶまで、コンパイルメニューでは、その固定が **[未インストール]** と表示されます。

### 切り替える前に新しいバージョンを試す

Typst プロジェクトを開いているとき、より新しい Typst がインストールされていれば、設定の Typst のタブに **新しいバージョンを試す** が表示されます。**Typst 0.15.1 で確認**（または表示されている別のバージョン）を選びます。Oleafly は、一時フォルダでプロジェクトを 2 回ビルドします。プロジェクトの現在のバージョンで 1 回、新しいバージョンで 1 回です。プロジェクトの中身は何も変わりません。

レポートには、それぞれのビルドが成功したか、ページ数、エラーと警告が表示されます。ページ数が変わる場合は、その旨が示されます。**Typst 0.15.1 で新たに報告**には、新しいバージョンだけが報告するメッセージが、**Typst 0.15.1 では報告されない**には、なくなるメッセージが一覧されます。メッセージをクリックすると、そのファイルの該当行が開きます。

結果に問題がなければ、**Typst 0.15.1 に切り替える**で、プロジェクトを新しいバージョンに固定します。何かを直したあとは、**もう一度確認**で、両方のビルドをやり直します。

### 言語サーバーはバージョンに従う

Tinymist は、Typst ファイルでの補完、ホバーヘルプ、名前の変更、整形を支えています（[コードインテリジェンス](/docs/code-intelligence/#typst-files)を参照）。Typst のマイナーバージョンごとに専用の Tinymist リリースがあり、プロジェクトは自分の Typst バージョンに合うものと通信します。

組み込みの Tinymist は Typst 0.15 に対応しています。古い系列に固定されたプロジェクトを開くと、Oleafly は同じチェックサムの確認をしながら、合う Tinymist をバックグラウンドでダウンロードし、ステータスには「このプロジェクトの Typst のバージョンに合わせて、Tinymist 0.13.30 をダウンロードしています。」と表示されます。ダウンロードに失敗したら、Oleafly はあとでもう一度試します。インストール済みのどの Typst でももう必要のない Tinymist のダウンロードを設定が見つけると、**使われていない言語サーバーのダウンロードを削除**が表示されます。

### 各バージョンでできること

古いバージョンが残っているのは、そのバージョンで始めたプロジェクトが同じようにビルドされ続けるようにするためです。一部の機能は、Typst のバージョン自体が何に対応しているかに左右されます。

| 機能 | 0.11 | 0.12 | 0.13 | 0.14 以降 |
| --- | --- | --- | --- | --- |
| プロジェクトのフォントのみ | 非対応 | 対応 | 対応 | 対応 |
| 再現可能なビルド | 非対応 | 対応 | 対応 | 対応 |
| PNG と SVG の書き出しでのページ範囲 | 非対応 | 対応 | 対応 | 対応 |
| PDF/A | 非対応 | PDF/A-2b | PDF/A-2b、PDF/A-3b | Typst が提供するすべての PDF/A レベル |
| PDF/UA-1 | 非対応 | 非対応 | 非対応 | 対応 |
| プロジェクトフォルダに置いたパッケージ | 非対応 | 対応 | 対応 | 対応 |
| HTML の書き出し、および Typst の HTML を経由した Word や Markdown の書き出し | 非対応 | 非対応 | 対応 | 対応 |
| [ソースと PDF の同期](/docs/synctex/) | 非対応 | 非対応 | 対応 | 対応 |
| コンパイルのたびにタグ付き PDF を作成 | 非対応 | 非対応 | 非対応 | 対応 |

フォントの選択画面は、Typst 0.15 以降では、各フォントの出どころを示せます。設定がプロジェクトの使うバージョンに適用できないときは、コンパイルメニューにその設定が **新しい Typst が必要** と表示されます。

## Typst Universe のパッケージ

Typst ツールバーの右端にあるパッケージのアイコン、**Typst パッケージ**を選びます。名前、キーワード、カテゴリで Typst Universe を検索します。各パッケージには最新バージョンが表示され、プロジェクトが使うより新しい Typst を必要とするパッケージには、その旨が表示されます。「Typst 0.14.0 が必要です。このプロジェクトは Typst 0.13.1 を使っています。」

**import を挿入**は、開いている Typst ファイルの先頭に `#import` 行を書き込みます。**import をコピー**は、代わりにそれをクリップボードに置きます。

Typst は、`@preview` パッケージを、コンパイルで初めて読み込むときにダウンロードし、すべてのプロジェクトが共有するキャッシュに保存します。パッケージの一覧もキャッシュされます。オフラインでは、ダイアログに最後に取得した一覧が、その日付とともに表示されます。

### 新しいリリース

Typst Universe にあるものより古いリリースを import が指しているとき、そのバージョン番号に下線が引かれ、「cetz 0.4.2 が利用できます。この import は 0.3.4 を使っています。」のようなヒントが表示されます。ヒントのカードには **0.4.2 に更新**があり、import のバージョン番号を書き換えます。新しいリリースでパッケージの呼び出し方が変わることがあるので、受け入れる前にパッケージの変更履歴を読んでください。import にマウスを重ねると、**Typst Universe で開く**も表示されます。

### パッケージをプロジェクトの中に置く

同じダイアログの **プロジェクトのパッケージ**にある **パッケージをプロジェクトに取り込む**は、プロジェクトが読み込むすべてのパッケージを、プロジェクトの最上位にある `typst-packages` フォルダにコピーします。それらのパッケージが読み込むパッケージもコピーし、**プロジェクトフォルダのパッケージを使う**をオンにします。

それ以降、Typst は最初に `typst-packages` を探します。パッケージを取り込んだプロジェクトは、オフラインでも、どのコンピュータでもコンパイルでき、そのフォルダはソースと一緒に Git に入れられます。取り込んでいないパッケージは、これまでどおり共有キャッシュから取得されます。これには Typst 0.12 以降が必要で、0.11 に固定されたプロジェクトでは、先にバージョンを切り替えるようダイアログが求めます。

パッケージがまだキャッシュにないときは、ダイアログがその名前を示します。「次のパッケージはパッケージキャッシュにありません: …」。オンラインで一度コンパイルしてから、もう一度取り込んでください。

### オフラインモード

**設定 → 一般**で**オフラインモード**をオンにすると、Typst は何もダウンロードできません。すべてのパッケージが、すでに共有キャッシュか `typst-packages` にある必要があります。ないものがあるとコンパイルが失敗し、メッセージにそのパッケージ名が示されるので、次にオンラインになったときに何を取得すべきか分かります。

## フォント

Typst は、4 か所でフォントを見つけます。Typst に組み込まれたフォント、お使いのコンピュータにインストールされたフォント、Oleafly でダウンロードしたフォントパック、プロジェクトの中のフォントフォルダです。フォントファイルを、プロジェクトの最上位にある `fonts` という名前のフォルダに置くと、コンパイラと言語サーバーの両方がそれを拾います。追加のフォルダは、`project.json` の `typst.font_paths` に一覧できます。プロジェクトの外にあるフォルダは無視されます。

コンパイルメニューの **フォント（このプロジェクト）** では、**システムフォントを使う**が既定です。**プロジェクトのフォントのみ**にすると、Typst はこのコンピュータにインストールされたフォントを読まなくなります。そうすると PDF はどのマシンでも同じに仕上がり、文書がプロジェクトにないフォントを求めても、共同執筆者のマシンではなく、自分のコンピュータでそれに気づけます。

本文のフォントを選ぶには、Typst ツールバーのスライダーのアイコンである **文書の設定**を開き、**本文フォント**をクリックします。一覧には、プロジェクトの現在のフォント設定で Typst が見つけられるすべてのファミリーが表示されます。Typst 0.15 以降では、各ファミリーに **プロジェクト**、**システム**、**フォントパック**、**組み込み**のラベルが付きます。1 つ選んで **適用**を選ぶと、Oleafly はそれを文書の `#set` ルールに書き込みます。

### フォントパック

**設定 → ダウンロード → フォント**には、Typst 用の無料のフォントパックが 5 つあります。**中国語・日本語・韓国語**、**クラシックな本文用**、**モダンなサンセリフとセリフ**、**コード**、**アイコンと絵文字**です。パックをダウンロードすると、すべての Typst プロジェクトでそのフォントを名前で使えるようになり、そのタブにある Lato、PT Sans、PT Serif のダウンロードも同じです。パックがコンパイルに加わるのはダウンロードがすべて終わってからなので、途中までのダウンロードがビルドに影響することはありません。

**プロジェクトのフォントのみ**または**再現可能なビルド**にしたプロジェクトは、フォントパックを読み込みません。その場合は、フォントファイルをプロジェクトの `fonts` フォルダにコピーしてください。

### 文字が四角で表示されるとき

Oleafly は、コンパイルのたびに、使えるどのフォントでも描けなかった文字がないかを確認します。Typst はそうした文字を四角で描きます。見つかった場合は、コンパイルに警告が付き、エディタの上に通知が表示されます。

- **空の四角**は、Typst が使えるどのフォントにもその文字がないことを意味し、警告にはその一部が示されます。フォントパックがそれをカバーしている場合、たとえば CJK のテキストには中国語・日本語・韓国語のパック、絵文字にはアイコンと絵文字のパックが当てはまり、通知にはダウンロードサイズ付きで**フォントをダウンロード**が、ログには**ダウンロードしてコンパイル**が表示されます。そうでなければ、その文字を持つフォントをプロジェクトの `fonts` フォルダに追加します。
- **疑問符付きの四角**は、Typst が代替のフォントで文字を描いたことを意味します。**文書の設定**の**本文フォント**で、その文字を持つフォントを指定するか、`#set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))` のようなフォントリストで指定します。
- **プロジェクトのフォントのみ**にしたプロジェクトでは、フォントパックとシステムフォントは使われません。`fonts` フォルダにフォントを追加するか、プロジェクトを**システムフォントを使う**と**標準ビルド**に切り替えます。

通知の**文書の設定**を押すと、本文フォントを選ぶパネルが開きます。通知を閉じると、その警告については非表示になります。

## ビルドバリアントと sys.inputs

ビルドバリアントとは、文書が `sys.inputs` を通じて読み取る、名前付きの値の集まりです。1 つのソースから、匿名のレビュー用コピーと最終版のコピー、透かし付きの下書きなど、異なる PDF を作る必要があるときに使います。

各値で何をするかは、文書が決めます。値は常にテキストとして届きます。

```typst
#let draft = sys.inputs.at("draft", default: "false") == "true"

#if draft [*Draft. Do not circulate.*]
```

バリアントを設定するには、次のようにします。

1. **文書の設定**を開き、**ビルドバリアント**までスクロールします。
2. **バリアントを追加**を選び、`review` のような名前を付けます。
3. **値を追加**を選び、**名前**に `draft`、**値**に `true` を入力します。
4. **適用**を選びます。
5. コンパイルメニューを開きます。**バリアント（このプロジェクト）** に `review` が表示されます。それを選んでコンパイルします。

**バリアントなし**は、バリアントの値なしでビルドします。選んだバリアントはこのコンピュータにだけ記憶されるので、共同執筆者は同じプロジェクトから別のバリアントをビルドできます。バリアント自体は `project.json` に保存されます。書き出しでも、選択したバリアントが使われます。

すべてのビルドで受け取るべき値は、`project.json` の `typst.inputs` に書きます。バリアントが同じ名前の値を設定した場合は、バリアントが優先されます。

## 再現可能なビルド

コンパイルメニューの **ビルド（このプロジェクト）** で **再現可能なビルド**にすると、同じソースからどのコンピュータでも同じ PDF が得られます。プロジェクトのフォントと Typst に組み込まれたフォントだけを使い、PDF の日付を最後の Git コミットにします。Git リポジトリではないプロジェクトでは、日付は 1970 年 1 月 1 日に固定されます。

これが重要になるのは、アーカイブへの登録や CI での比較のために、PDF がチェックサムと一致しなければならないときです。Typst 0.12 以降が必要です。オンの間は、**システムフォントを使う**は選べません。**標準ビルド**が既定です。

![Typst は入力に合わせてコンパイルされ、追加した行が PDF に反映されます。](https://cdn.oleafly.com/images/gifs/desktop/typst-live.gif?v=2)

## 自動コンパイルによるライブプレビュー

コンパイルメニューで **自動コンパイル**を **オン**にします。Typst プロジェクトでは、Oleafly は Typst のプロセスを 1 つ動かし続けます。開いているファイルは、入力を止めて少し経つと自動で保存され、Typst がコンパイルし、プレビューは同じスクロール位置で再読み込みされます。ライブプレビュー専用の設定はありません。自動コンパイルがライブプレビューです。

Typst の起動中、メニューには「Typst を起動しています」と表示されます。エラーが繰り返されて停止した場合は、メニューにそう表示され、次に編集すると再び起動します。**コンパイルを停止**はプロセスを終了させ、やはり次の編集で再び起動します。LaTeX と Markdown のプロジェクトでは、自動コンパイルの扱いが異なります。[コンパイル](/docs/compiling/#auto-compile)を参照してください。

## コマンドラインからビルドする

`oleafly` コマンドは、アプリを開かずにプロジェクトをビルドします。Oleafly に付属しており、PATH に通す方法は[コマンドラインツール](/docs/cli/#install)で説明しています。

Typst プロジェクトでは、`oleafly build` と `oleafly watch` が `project.json` を読み、アプリと同じ設定を使います。固定されたバージョン、取り込んだパッケージ、フォントフォルダ、システムフォントのスイッチ、入力、再現可能なビルドです。

- `--variant review` はバリアントをビルドします。プロジェクトが定義していない名前を指定するとビルドが止まり、メッセージに、存在するバリアントが一覧されます。
- `--offline` はパッケージのダウンロードを止めます。アプリのオフラインモードと同じです。
- 固定されたプロジェクトは、ちょうどその Typst でしかビルドされません。CLI は、`OLEAFLY_TYPST`、アプリがダウンロードしたバージョン、CLI の隣にある `typst`、`PATH` の順に探します。どれも固定されたバージョンを報告しなければ、Typst が実行される前にビルドが止まり、インストール方法が示されます。
- 固定のないプロジェクトは、`OLEAFLY_TYPST` が設定されていればそれを使います。そうでなければ、**設定 → ダウンロード**か `oleafly typst default` で選んだ既定のバージョンを使い、既定を選んでいない場合は、同梱の Typst か `PATH` にある Typst を使います。
- `oleafly doctor` は、見つけたすべての Typst と、ビルドが使う設定を一覧します。固定されたバージョンが見つからないと失敗します。

使っている Typst に適用できない設定があると、ビルドは、たとえば Typst 0.11.1 ではシステムフォントを無視できない、といった注記を表示します。ターミナルのエラーには、Typst 自身のヒントが含まれます。

## LaTeX プロジェクトを Typst に変換する

LaTeX プロジェクトを開き、⌘K（Ctrl+K）を押して、**Typst のプロジェクトに変換**を実行します。新しいプロジェクトに名前を付けて、**変換**を選びます。LaTeX プロジェクトはそのままです。Oleafly は、それとは別の Typst プロジェクトを作ります。

- Pandoc が本文、数式、図、表を変換します。Pandoc がまだ設定されていなければ、Oleafly が先に設定します。
- `\input`、`\include`、`\subfile` で取り込まれた各ファイルは、それぞれ独立した `.typ` ファイルになります。
- BibTeX ファイルは、そのままコピーされます。
- Typst が新しいプロジェクトをコンパイルして確認します。

レポートには、プロジェクトがコンパイルできるかどうかと、変換されたものの数が表示されます。ソースファイル、図、表、ディスプレイ数式、相互参照、数式変換で修正された式、コピーされたファイルの数と、選ばれた参考文献スタイルです。**要確認**には、手作業で直すべきものが一覧されます。たとえば、見つからない include や画像、Typst が表示できない画像形式、変換ツールが扱えなかった数式、Typst に対応するもののない BibTeX スタイル、複数行の数式の 1 行に付いていたラベル（現在は数式全体を指します）などです。コンパイルのエラーと警告は、そのファイルと行にリンクしています。

**Typst のプロジェクトを開く**を選ぶと、そちらに切り替わります。新しいプロジェクトは、既定の Typst バージョンを固定します。Oleafly を開いたままの間は、コマンドパレットの **Typst への変換レポートを表示**で、レポートを再表示できます。

プロジェクト全体ではなく 1 つのファイルを変換するには、ツールのページの [LaTeX から Typst へ](/docs/tools/latex-to-typst/)を使います。

## 関連ページ

- ツールバーと最初の文書は、[Typst で書く](/docs/writing/typst/)で説明しています。
- ログ、コンパイルメニュー、オフラインモードは、[コンパイル](/docs/compiling/)で説明しています。
- PNG、SVG、HTML、PDF/A、PDF/UA は、[プロジェクトの書き出しと変換](/docs/export/#typst-images-and-html)で説明しています。
- Typst のソースを読むチェックは、[プリフライトのチェック](/docs/preflight/#typst-projects)で説明しています。
