---
description: Typstのチュートリアルです。
---
# Typstで執筆するには

さあ始めましょう！あなたが大学で専門的なレポートを書くことになったとしましょう。そこには文章、数式、見出し、図が含まれています。
書き始めるには、まずTypst appで新しいプロジェクトを作成します。エディターに移動すると、2つのパネルが表示されます。
1つは文書を作成するソースパネル、もう1つはレンダリングされた文書が表示されるプレビューパネルです。

![Typst app screenshot](1-writing-app.png)

レポートの良い切り口はすでに考えてあるので、まずは導入を書いてみましょう。
エディターパネルにいくつかのテキストを入力してください。テキストがすぐにプレビューページに表示されるのがわかるでしょう。

```example
In this report, we will explore the
various factors that influence fluid
dynamics in glaciers and how they
contribute to the formation and
behaviour of these natural structures.
```

_このチュートリアル全体を通して、このようなコード例を紹介します。アプリと同様に、最初のパネルにはマークアップが含まれ、2番目のパネルにはプレビューが表示されます。何が起こっているかわかりやすいように例に合わせてページを縮小しています。_

次のステップは、見出しを追加して、いくつかのテキストを強調することです。
Typstでは、頻繁に使う書式をシンプルなマークアップで表現するようになっています。見出しを追加するには `=` の文字を入力します。テキストを斜体で強調するには、テキストを `[_アンダースコア_]` で囲みます。

```example
= Introduction
In this report, we will explore the
various factors that influence _fluid
dynamics_ in glaciers and how they
contribute to the formation and
behaviour of these natural structures.
```

簡単でしたね！新しい段落を追加するには、2行のテキストの間に空行を追加するだけです。
その段落に小見出しが必要な場合は、`=` の代わりに `==` を入力して作成します。
`=` の数が見出しのネストレベルを決定します。

次に、氷河の動態に影響を与える要因をいくつか列挙してみましょう。
そのために、ここでは番号付きリストを使いましょう。リストの各項目について、行の先頭に `+` 文字を入力します。
すると、Typstが自動的に項目を番号付けしてくれるのです。

```example
+ The climate
+ The topography
+ The geology
```

箇条書きリストを追加したい場合は、`+` 文字の代わりに `-` 文字を使用します。
また、リストをネストすることもできます。
例えば、上記のリストの最初の項目にサブリストを追加するには、それをインデントします。

```example
+ The climate
  - Temperature
  - Precipitation
+ The topography
+ The geology
```

## 図表を追加する {#figure}

あなたは「レポートに図表を入れるともっと良くなる」と考えているとします。やりましょう。
Typstでは、PNG、JPEG、GIF、SVGの形式の画像をサポートしています。
プロジェクトに画像ファイルを追加するには、まず左サイドバーのボックスアイコンをクリックして _ファイルパネル_ を開きます。
ここにはプロジェクト内のすべてのファイルのリストが表示されます。
現在、ここにあるのはあなたが書いているメインのTypstファイルだけです。
別のファイルをアップロードするには、右上隅の矢印のボタンをクリックします。
これによりアップロードダイアログが開き、コンピュータからアップロードするファイルを選択できます。
レポートに用いる画像ファイルを選んでください。

![Upload dialog](1-writing-upload.png)

以前にも見てきたように、Typstでは特定の記号（ _マークアップ_ と呼ばれる）が特有の意味を持ちます。
`=`、`-`、`+`、`_` をそれぞれ見出し、リスト、強調テキストを作成するために使用することができます。
しかし、文書に挿入したいもの全てに特別な記号を割り当てると、すぐに分かりづらく、そして扱いづらくなってしまいます。
そのため、Typstでは一般的な書式にのみマークアップ記号を用意し、それ以外は全て _関数_ を使って挿入します。

ページに画像を表示させるためには、Typstの [`image`] 関数を使用します。

```example
#image("glacier.jpg")
```

一般的に、関数は一連の _引数_ に対して何らかの出力を生成します。
マークアップ内で関数を _呼び出す_ 時は、あなたが関数の引数を指定すると、Typstがその結果（関数の _戻り値_ ）を文書に挿入してくれます。
今回の場合、`image` 関数は一つの引数として画像ファイルへのパスを受け取ります。
マークアップで関数を呼び出すには、まず `#` 文字を入力し、直後に関数の名前を記述します。
その後、引数を丸括弧で囲みます。
Typstは引数リスト内でさまざまなデータ型を認識します。
私たちの画像のファイルパスは短い [文字列]($str) ですので、二重引用符で囲む必要があります。

挿入された画像はページ全体の幅を使います。これを変更するには、`image` 関数に `width `引数を渡します。
これは _名前付き_ 引数であり、`引数の名前: 引数の値` という形式で指定されます。
複数の引数がある場合はカンマで区切ります。そのため、ここでは先ほど指定したファイルパスの後ろにカンマを付ける必要があります。

```example
#image("glacier.jpg", width: 70%)
```

`width` 引数は [相対的な長さ]($relative) です。
上の例では、画像がページの幅の `{70%}` を占めるようにパーセンテージを指定しています。
また、`{1cm}` や `{0.7in}` のような絶対値を指定することもできます。

テキストと同様に、画像もデフォルトではページの左側に配置されます。さらに、図表の説明（キャプション）も欠けています。
これらを修正するために、[figure]($figure) 関数を使用しましょう。
この関数には、名前付きでない通常の引数（位置引数）として、図表を指定する必要があります。さらにオプションとして、図表に付ける説明文（`caption`）を名前付き引数で指定できます。

`figure` 関数の引数リスト内では、Typstは既にコードモードになっています。
これは、 `image` 関数の呼び出し前にある `#` 記号を削除する必要があることを意味します。
`#` 記号は、マークアップ内でテキストと関数呼び出しを区別するために書くものなのです。

キャプションの中には、任意のマークアップを含めることが出来ます。
ある関数の引数としてマークアップを指定するためには、それを角括弧 `[ ]` で囲みます。この「マークアップが角括弧で囲まれている構造」のことを、_コンテンツブロック_ と呼ばれます

```example
#figure(
  image("glacier.jpg", width: 70%),
  caption: [
    _Glaciers_ form an important part
    of the earth's climate system.
  ],
)
```

あなたはレポートの執筆を続けるうちに、今度は先ほど挿入した図を文中から参照したくなったとします。
その場合、まず図にラベルを付けます。
ラベルとは、文書内の要素を一意に識別するための名前のことです。先ほど挿入した図の後ろに、その図のラベルを山括弧 `< >` で囲んで書き加えます。
これで、テキスト内で `[@]` 記号を書いた後ろにラベル名を指定すると、その図を参照できるようになりました。
見出しや方程式もラベルを付けて参照可能にすることができます。

```example
Glaciers as the one shown in
@glaciers will cease to exist if
we don't take action soon!

#figure(
  image("glacier.jpg", width: 70%),
  caption: [
    _Glaciers_ form an important part
    of the earth's climate system.
  ],
) <glaciers>
```

<div class="info-box">

これまでに、コンテンツブロック（角括弧 `[ ]` 内のマークアップ）と文字列（二重引用符 `" "` 内のテキスト）を関数に渡してきました。
どちらもテキストを含んでいるように見えますが、違いは何でしょうか？

コンテンツブロックはテキストを含むことができますが、それ以外にもさまざまなマークアップ、関数呼び出しなどを含むことができます。
一方、文字列は本当に _文字の並び_ に過ぎません。

例えば、image 関数は、引数として画像ファイルへのパスが渡されることを想定しています。ここに文章の段落や他の画像を渡しても意味がありません。
image関数の引数としてマークアップがダメで文字列が許可されるのは、そういうわけなのです。
それとは反対に、文字列はコンテンツブロックが期待される場所であればどこにでも書くことが出来ます。なぜなら、文字列は単なる文字の並びであり、文字の並びは有効なコンテンツの一種だからです。

</div>

## 参考文献の追加 {#bibliography}

レポートを作成する際には、その主張を裏付ける必要がありますよね。
参考文献を文書に追加するには、[`bibliography`]($bibliography) 関数を使用できます。
この関数は、引数として参考文献ファイルへのパスが渡されることを想定しています。

Typstでは、ネイティブな参考文献の形式として[Hayagriva](https://github.com/typst/hayagriva/blob/main/docs/file-format.md)を使用していますが、
互換性のためにBibLaTeXファイルも使用できます。
クラスメートが既に文献調査を行い、`.bib` ファイルを送ってくれたので、それを使用しましょう。
ファイルパネルを通じてファイルをアップロードし、Typst appでアクセスできるようにします。

文書に参考文献が追加されている場合、参考文献欄にある文献を文中で引用することができます。
引用はラベルへの参照と同じ構文を使用します。デフォルトでは、文中に文献の引用を記述した時点で初めて、その文献がTypstの参考文献セクションに表示されるようになっています。
Typstはさまざまな引用および参考文献のスタイルをサポートしています。詳細については [リファレンス]($bibliography.style)を参照してください。

```example
= Methods
We follow the glacier melting models
established in @glacier-melt.

#bibliography("works.bib")
```

## 数式 {#maths}

方法に関する節を肉付けした後、文書の主要な部分である方程式に進みます。
Typstには組み込みの数学記法があり、独自の数学表記を使用します。
簡単な方程式から始めましょう。Typstに数学的な表現を期待することを知らせるために、`[$]` 記号で囲みます。

```example
The equation $Q = rho A v + C$
defines the glacial flow rate.
```

方程式はインラインで表示され、周囲のテキストと同じ行に配置されます。
それを独立した行にしたい場合は、方程式の最初と最後にそれぞれ1つずつスペースを挿入する必要があります。

```example
The flow rate of a glacier is
defined by the following equation:

$ Q = rho A v + C $
```

Typstでは、単一の文字 `Q`, `A`, `v`, `C` はそのまま表示され、一方で `rho` はギリシャ文字に変換されているのがわかります。
数式モードでは、単一の文字は常にそのまま表示されます。しかし、複数個が連なっている文字は記号、変数、または関数名として扱われます。
異なる種類の文字どうしの乗算を（乗算記号を省略して）示すためには、文字と文字の間にスペースを挿入してください。

複数の文字からなる変数を表したい場合は、変数の名前を引用符で囲みます。

```example
The flow rate of a glacier is given
by the following equation:

$ Q = rho A v + "time offset" $
```

レポートには総和の式も必要です。
`sum` 記号を使用して、総和の範囲を下付き文字と上付き文字で指定することができます。

```example
Total displaced soil by glacial flow:

$ 7.32 beta +
  sum_(i=0)^nabla Q_i / 2 $
```

シンボルや変数に下付き文字を追加するには、`_` の文字を入力してから下付き文字を入力します。
同様に、上付き文字を追加するには `^` の文字を使用します。
もし下付き文字や上付き文字が複数の要素からなる場合は、それらを丸括弧で囲む必要があります。

上記の例から分数の挿入方法もわかると思います。
分子と分母の間に `/` の文字を置くだけで、Typstは自動的にそれを分数に変換します。
Typstでは、丸括弧のネストをスマートに解決するようになっています。プログラミング言語や関数電卓のように、丸括弧を入れ子にした式を入力すると、
Typstは丸括弧で囲まれた部分式を適切に解釈して自動的に置き換えます。

```example
Total displaced soil by glacial flow:

$ 7.32 beta +
  sum_(i=0)^nabla
    (Q_i (a_i - epsilon)) / 2 $
```

数学のすべての概念に特別な構文があるわけではありません。
代わりに、先程の `image` 関数のように関数を使用します。
例えば、列ベクトルを挿入するには、`vec` 関数を使用できます。
数式モード内では、関数呼び出しは `#` で始める必要はありません。

```example
$ v := vec(x_1, x_2, x_3) $
```

数式モード内でのみ使用可能な関数もあります。
例えば、[`cal`]($math.cal) 関数は集合などに一般的に使用されるカリグラフィ文字を表示するために使われます。
数式モードが提供するすべての関数の完全なリストについては、[リファレンスの数式セクション]($category/math)を参照してください。

もう一つ、矢印などの多くの記号には多くのバリエーションがあります。
こうした様々なバリエーションの中から特定の記号を選択するには、その記号のカテゴリ名の後に、ドットと具体的な記号の種類を示す修飾子を追加します。

```example
$ a arrow.squiggly b $
```

この表記法はマークアップモードでも利用可能ですが、そこでは記号名の前に `#sym.` を付ける必要があります。
利用可能なすべての記号については[記号セクション]($category/symbols/sym)を参照してください。

## まとめ {#review}

あなたはTypstで基本的な文書を書く方法を学びました。テキストの強調やリストの書き方、画像の挿入、コンテンツの配置、Typstにおける数学的な式の組版などを学びました。また、Typstの関数についても学びました。
Typstでは文書に挿入できるさまざまなコンテンツがあります。たとえば、[表]($table)や[図形]($category/visualize)、[コードブロック]($raw)などです。さらにこれらや他の機能について詳しく学ぶには[リファレンス]($reference)を参照してください。

ここまでで、レポートの執筆は完了しました。
あなたは右上のダウンロードボタンをクリックしてPDFを保存したはずです。
しかし、あなたはレポートがあまりにも素朴に見えると感じるかもしれません。
次のセクションでは、文書の外観をカスタマイズする方法を学びます。
