用 Typst 寫作

選擇 Typst 範本，並在編譯好的 PDF 旁邊編輯它的 .typ 原始碼。工具列會替你寫出 Typst 語法，所以每項更動都留在原始碼中，供你閱讀與編輯。如果你不想看到標記，請把檔案切換到視覺化模式。

Typst 範例，含格式工具列、原始碼與編譯後的報告。 開啟完整螢幕截圖

編譯一份小型報告

1. 選擇 「新增專案 → 使用範本 → Blank Typst document」。
2. 將它命名為 「Measurement note」，並開啟 main.typ。
3. 貼上下面的範例，然後選擇 「重新編譯」，或按 ⌘Enter / Ctrl+Enter。

main.typ

#set document(title: "Measurement note", author: "Alex Chen")
#set page(paper: "a4", margin: 25mm)
#set heading(numbering: "1.")

= Measurement note
A short report on repeated measurements.

== Method <method>
We collect three observations and compare their mean.

$ overline(x) = (1 + 2 + 3) / 3 = 2 $

== Results
See @method for the procedure.

#table(
  columns: 2,
  [Run], [Value],
  [1], [1],
  [2], [2],
  [3], [3],
)

PDF 應該會顯示編號的標題、一個行間公式、一個指向方法章節的參照，以及一個兩欄的表格。

若要在你輸入時看到 PDF 隨之變化，請開啟 「重新編譯」 旁邊的箭頭，並把 「自動編譯」 設為 「開啟」。在 Typst 專案中，這就是即時預覽。請參閱使用自動編譯的即時預覽。

下載範例原始碼

每一個工具列工具

使用格式工具之前先選取文字，就能包住那段文字。沒有選取時，工具列會插入一個你可以直接輸入蓋過的佔位文字。當編輯器太窄、放不下所有按鈕時，放不下的按鈕會移到 「更多格式選項」（…）中。這些工具大多數也能在編輯器的右鍵選單中找到。

程式碼 / 視覺化

工具列開頭的切換開關會改變檔案的顯示方式。「程式碼」 顯示 Typst 原始碼。「視覺化」 會在原處繪製標題、強調、清單、數學式、影像、表格、參照與註腳，並在游標所在那一行顯示出原始碼。兩種模式下的檔案是同一個。Typst 的視覺化模式有詳細說明。

復原

復原你最近的一次編輯。⌘Z / Ctrl+Z。沒有可復原的內容時，按鈕會呈灰色。

重做

重新套用已復原的編輯。⌘Shift+Z / Ctrl+Shift+Z。

標題 → 標題

選取一個標題並選擇 「標題」。= Title。

標題 → 章節

在文件中加入一個章節。== Section。

標題 → 小節

加入章節之下的一層。=== Subsection。

標題 → 次小節

加入第四層標題。==== Subsubsection。

標題 → 次要標題

加入第五層標題。===== Minor heading。

標題 → 段落標題

加入第六層標題。====== Paragraph heading。

粗體

選取「three observations」。*three observations*；⌘B / Ctrl+B。

斜體

選取要強調的詞。_term_；⌘I / Ctrl+I。

底線

選取一個片語。#underline[phrase]。

刪除線

標示一個過時的片語。#strike[phrase]。

行內程式碼

選取檔名或變數名稱。會用反引號把它包住。

插入連結

先替換 url，再替換 text。#link("url")[text]。

從專案引用

依鍵、作者或標題搜尋專案的參考文獻，並挑選一個項目。Oleafly 會寫入 @key。如果文件還沒有 #bibliography 呼叫，Oleafly 會加上一個。清單底部的 「尋找並新增引用…」 會開啟搜尋，以尋找新的來源。請參閱加入引用。

插入交互參照

從專案的清單中挑選一個標籤，寫入 @label。在範例中，選擇 method 就會得到 @method。「在此加入標籤」 則是改為在游標處的項目上放一個新標籤。

加入標籤

把游標放在標題、圖片或公式中，然後選擇 「加入標籤」。在範例的 Results 標題上，Oleafly 會加上 <sec:results>。如果該項目已經有標籤，按鈕就會選取它。

插入註腳

把游標放在一個詞後面。#footnote[note text]。

插入引述區塊

把游標放在新的一行。#quote(block: true)[quote]。

插入圖片

開啟圖片對話方塊。從 「專案影像」 挑選影像，或選擇 「從磁碟匯入…」，然後設定它的寬度、圖說、標籤、替代文字與位置。游標位於既有的 #figure 內時，同一個按鈕會開啟 「編輯圖片」，讓你變更其中任何一項。請參閱加入附圖說的圖片。

插入表格

開啟格線並挑選列數與欄數。Oleafly 會插入一個 #figure，內含帶標題列與頂線、中線、底線的 table，以及 caption: [Caption] 和標籤 <tab:label>。替換圖說、標籤與空白的儲存格。若要改用試算表建立表格，請參閱來自資料檔案的表格。

插入影像

匯入影像，然後把選取的檔名換成它的相對路徑。#image("image-filename")。你也可以把影像檔案貼上或拖放到編輯器中，Oleafly 會把它儲存到專案，並插入使用它的圖片。

繪製圖表

以 Typst 模式開啟圖表編排器。在畫布上繪製或編輯 fletcher 程式碼，然後選擇 「以 Typst 插入」，把圖表放在游標處。第一次預覽會從 Typst Universe 下載 fletcher 套件，所以你需要連網。

影像轉 Typst

選擇公式或一段文字的截圖，它就會被轉寫成 Typst，放在游標處。它會用工具所用的模型，除非你另外選擇，否則那是本機的 Ollama 模型。如果你沒有選擇，而且 Ollama 沒有執行或沒有能讀取圖片的模型，它就會改用助理的模型，圖片也會送到那個供應商。檢查結果並編譯它。

清單 → 項目符號清單

開始一份觀察清單。- Item。

清單 → 編號清單

開始一連串步驟。+ Item。

公式

選取 x 並點擊公式圖示。$x$。

行間公式

獨立成行的公式。$ x $，每個 $ 內側都有一個空格。

編號公式

帶標籤的行間公式，例如 $ x $ <eq:label>。只有在文件有編號規則時，Typst 才會替公式編號。如果你的文件沒有，會出現一則提示，提供 「加入規則」，它會在檔案頂端附近加上 #set math.equation(numbering: "(1)")。

多行對齊公式

數個公式在 & 處對齊，列與列之間用 \。$ a &= b \ c &= d $。

分數

插入 frac(a, b)；當游標還不在數學式中時，會用 $ 包住。選取了文字時，選取的內容會成為分子。

符號

開啟符號選擇器，搜尋符號並選取它。Oleafly 會以它的 Typst 名稱寫入：在數學式中是 arrow.r，在一般文字中是 #sym.arrow.r。

程式碼區塊

選取幾行程式碼，或替換佔位文字。會產生以三個反引號包住的區塊。在起始圍欄後面加上語言，即可進行語法醒目提示。

程式碼智慧 → 前往定義

把游標放在標籤、變數或函式上，然後選擇該動作，或按 F12。會開啟它定義的地方，即使在另一個檔案中也一樣。

程式碼智慧 → 尋找參考

列出標籤、變數或函式被使用的每一個位置。⇧F12。

程式碼智慧 → 重新命名符號

在整個專案中重新命名標籤、變數或函式。F2。程式碼智慧涵蓋這三項。

Typst 套件

列最右端的套件圖示會搜尋 Typst Universe 並插入一行 #import。詳情請見套件、設定與分析。

文件分析

列出文件的標題、圖片、表格、公式、標籤、引用與待辦事項，每一項都連結到它所在的行。請參閱文件分析。

文件設定

透過編輯文件的 #set 規則，變更頁面大小、邊界、字型、語言、對齊方式、行距與編號。請參閱文件設定。

專案資訊

顯示文件與任何選取範圍的字數、圖片數與數學式數量，以及校對結果。

尋找

在使用中的檔案中搜尋一個詞。⌘F / Ctrl+F。

前往 PDF

從游標跳轉到編譯後 PDF 中對應的位置。這個按鈕出現在 Typst 0.13 及更新版本上。請參閱在原始碼與 PDF 之間跳轉。

視覺化模式

在任何 .typ 檔案中，把工具列從 「程式碼」 切換到 「視覺化」。視覺化模式是同一個編輯器，只是標記會在原處繪製出來：

• 標題、粗體與強調文字、原始文字、連結與有顏色的文字
• 項目符號清單、編號清單與詞彙清單，並附有它們的標記
• 由 Typst 繪製的行內與行間數學式
• 影像與圖片，圖說以文字顯示
• 表格呈現為可以直接輸入的格線。選取儲存格會出現小工具列，可處理框線、對齊、列與欄。
• 參照與引用以標籤晶片顯示，註腳則顯示為小標記

把游標放在某一行上，它的原始碼就會回來，讓你編輯。移開後，繪製出的形式就會回來。檔案頂端的 #set、#show、#import 與 #let 行會摺疊成 「顯示文件設定」 列，你可以點擊它來展開。視覺化模式無法繪製的任何內容，會以原始碼的形式留在畫面上。每個工具列按鈕在兩種模式下都寫出相同的 Typst，而行號、尋找、拼字與編譯錯誤也都持續運作。

新專案以程式碼模式開啟，而且每個專案都會記住你離開時的模式。視覺化編輯涵蓋這三種語言的切換。

輸入時的輔助

Typst 檔案享有與 LaTeX 檔案相同的輔助功能，並針對 Typst 語法設計：

• 點擊邊欄中的箭頭，可以把標題摺疊到下一個同層級的標題。程式碼區塊、內容區塊、公式與很長的引數清單也能摺疊。請參閱程式碼摺疊。
• 捲動時，游標上方的標題會固定在編輯器頂端。檔案上方的導覽列會標出你所在的章節，點擊其中一項就會跳到該標題。
• 輸入 $ 會補上結尾的 $，在空的一對之間輸入空格，就會變成行間數學式。在清單項目上，Enter 會開始下一個項目。Typst 輸入輔助列出了其餘的功能。
• Typst 語言伺服器會自動完成函式、檔案路徑、標籤、引用鍵、套件與參考文獻樣式。請參閱 Typst 自動完成。
• 在行首或空格之後輸入 /，即可使用片段：標題、圖片、表格、公式、註腳、大綱、參考文獻等等。
• ⌘/ / Ctrl+/ 會用 // 為選取的行加上或移除註解。

數學式預覽

游標位於公式內時，Typst 會把結果繪製在公式的正上方。預覽的選單可以讓它隱藏到你離開公式為止，或直接關閉它。

把像 $\frac{a}{b}$ 這樣的 LaTeX 數學式貼進 Typst 檔案，它下方會出現 「貼上為 Typst 數學式」 按鈕。點擊它，就能把你貼上的內容換成 Typst 數學式；或按 Esc 保留 LaTeX。對於檔案中已有的 LaTeX 數學式，請選取它，並從右鍵選單選擇 「將 LaTeX 數學式轉換為 Typst」。若只是一次性的轉換，方程式轉 Typst 工具可以在專案之外做同樣的事。

加入附圖說的圖片

1. 選擇工具列上的 「插入圖片」。
2. 在 「專案影像」 下挑選 plot.png，或選擇 「從磁碟匯入…」 把它複製進專案。
3. 選擇 「四分之三寬」，然後開啟 「新增圖說」 與 「新增標籤」。輸入圖說與標籤 fig:measurements。
4. 加上為螢幕閱讀器描述影像的 「替代文字」，如果圖片應該浮動到頁面頂端或底端，請挑選 「位置」。
5. 選擇 「插入圖片」。

Oleafly 會寫出像這樣的圖片：

#figure(
  image("figures/plot.png", width: 75%),
  caption: [Measurements across three runs.],
) <fig:measurements>

See @fig:measurements for the comparison.

之後若要變更圖片，請把游標放在其中，並再次選擇 「插入圖片」。對話方塊會以 「編輯圖片」 開啟，並帶入目前的值。

來自資料檔案的表格

在編輯器中按右鍵，並選擇 「從 CSV/XLSX 匯入表格…」。選擇 CSV、TSV、Excel 或 JSON 檔案，檢查預覽，並在需要時加上說明與標籤。「插入到游標處」 會寫出一個 Typst 表格，其線條規則與工具列的表格相同。Typst 會當作標記來讀取的儲存格文字會被跳脫。

開啟 「保持與資料檔案的連結」，讓表格與它的資料綁在一起。Oleafly 會把資料複製到專案的 data 資料夾，而表格會在每次文件編譯時讀取該檔案。編輯該檔案，表格就會在下次編譯時改變。從資料檔案匯入表格完整說明了這個對話方塊。

加入引用

使用 「從專案引用」 來引用，或輸入 @ 並從自動完成清單挑選一個鍵。在 Typst 中，引用鍵與文件標籤都使用 @；目標由參考文獻或標籤提供。

把參考文獻放在你希望參考文獻清單出現的位置：

#bibliography("references.bib")

檔案可以是 BibTeX（.bib）或 Hayagriva（.yml），而這個呼叫也可以指定一份檔案清單。你從參考文獻與引用加入的引用，會放進文件所宣告的檔案，並在該檔案需要時轉換為 Hayagriva。若要變更參考文獻樣式，請使用參考文獻面板底部的 「引用樣式」 選單，它會替你寫出 style: 引數。請參閱選擇 Typst 引用樣式。

套件、設定與分析

工具列最右端的三個按鈕作用於整份文件：

• 「Typst 套件」 會搜尋 Typst Universe 並寫出 #import 行。當 import 指定的是較舊的版本時，編輯器會提議更新。專案也可以保留自己的套件副本，讓它能離線編譯。請參閱套件與來自 Typst Universe 的套件。
• 「文件分析」 會列出標題、圖片、表格、公式、標籤、引用與待辦事項，並複製標題、作者、關鍵字與摘要，用於投稿表單。對話方塊開啟時 Typst 會讀取文件，所以編號與頁碼都是最新的。請參閱文件分析。
• 「文件設定」 會變更頁面大小、邊界、欄數、內文字型、大小、語言、對齊方式、行距，以及標題與公式的編號。Oleafly 會把你的選擇寫進主檔案的 #set 規則。專案的建置變體也放在這裡。請參閱文件設定。

錯誤與檢查

編譯失敗時，每個錯誤都會在它的檔案中加上底線，範圍就是 Typst 回報的確切區段。把滑鼠移到底線上，就能閱讀訊息與 Typst 的提示。常見的錯誤，例如未知的名稱、缺少的檔案或套件，或是未關閉的括號，都附有淺白的說明。請參閱原始碼中的編譯錯誤。

拼字與文法會檢查 Typst 檔案中的文字，包括圖說、表格儲存格，以及像 abstract: 這樣的範本欄位，並略過程式碼。預檢會檢查 Typst 原始碼是否有未解析的參照與引用、缺少的替代文字、缺少的影像、文件中繼資料，以及匿名審查的問題。

在原始碼與 PDF 之間跳轉

選擇工具列上的 「前往 PDF」，或按 ⌘⇧J / Ctrl+Shift+J，就能從游標跳轉到頁面。在 PDF 中，按住 ⌘ 或 Ctrl 並點擊一個字，就能跳回它所在的行，即使它位於以 #include 引入的檔案中也一樣。同步需要 Typst 0.13 或更新版本。請參閱原始碼與 PDF 同步。

格式化檔案

「格式化文件」 會用 typstyle 整理整個檔案。按 ⇧⌥F / Shift+Alt+F，或從右鍵選單選擇它。「格式化選取範圍」 只會格式化選取的行。若要在每次按 ⌘S / Ctrl+S 時格式化，請在 「設定 → 外觀 → 編輯器」 的 「Typst」 底下開啟 「儲存時格式化」。請參閱格式化 Typst 檔案。

Typst 版本

Oleafly 隨附 Typst 0.15.1，而 「設定 → 引擎 → Typst」 列出可下載的 Typst 0.11 到 0.15。新專案會鎖定預設版本，所以之後 Oleafly 隨附較新的 Typst 時，它的換行與頁數仍保持不變。若要更改單一專案的版本，請開啟 「重新編譯」 旁邊的箭頭，並在 「Typst 版本（本專案）」 底下選擇。語言伺服器會跟隨專案的版本。Typst 版本說明鎖定、缺少的版本，以及切換之前如何測試較新的版本。

整理與匯出

把長篇報告拆成多個檔案，並用 #include "sections/method.typ" 引入它們。讓圖片、資料、字型與參考文獻檔案都留在專案內，這樣原始碼 ZIP 就會帶著文件需要的一切。

編譯以檢查結果，然後開啟 「匯出」。它提供 「匯出為 PDF」、「匯出原始碼（.zip）」、「將頁面匯出為 PNG」 與 「影像與 HTML」，後者會用 Typst 本身寫出 PNG 或 SVG 頁面，或 HTML 檔案。在 Typst 0.13 及更新版本上，Word、HTML、Markdown、LaTeX 與純文字的匯出會經過 Typst 自己的 HTML 輸出，所以公式與參照都能保留。請參閱匯出與轉換專案。編譯說明記錄檔與編譯選項，檔案與資料夾則涵蓋專案的組織。

若要把既有的 LaTeX 專案移到 Typst，請參閱將 LaTeX 專案轉換為 Typst。