typst 是做什麼的？
Typst 是一個基於標記的排版系統，內建指令碼語言。一個二進位檔即可將 .typ 編譯為 PDF（預設）、PNG、SVG、HTML（實驗性）或多檔案包（實驗性）。此技能針對 Typst 0.15.x（經驗證為 0.15.1）；並會標記與舊版不同的行為。
關於 Typst 的訓練資料通常已過時（0.11–0.13 時代）。當不確定某個函式、參數或預設值時，請查閱
references/api-signatures.md，然後編譯一個測試（typst eval '<expr>'或一個 5 行檔案），而不是憑空猜測。
工作流程
- 釐清輸出目標：PDF（預設）、HTML、PNG/SVG、無障礙 PDF（PDF/UA）、歸檔用 PDF（PDF/A）？頁面大小、語言、字型、引用風格、模板/期刊？
- 從骨架（如下）或
examples/開始。如果是期刊/論文/履歷/簡報，請先搜尋套件：python3 scripts/search-packages.py "ieee paper"（請參閱references/packages-and-ecosystem.md）。 - 編寫檔案：將
set/show規則和匯入放在頂部，內容放在下方。大型專案可使用#include和#import拆分。 - 編譯並檢查：
typst compile main.typ— 閱讀診斷資訊（它們附有行:列和提示）。透過 PNG（typst compile main.typ 'p-{p}.png'）進行視覺驗證，或透過文字方式（typst compile main.typ - -f html --features html/pdftotext）驗證。詳細資訊請參閱references/pitfalls-and-debugging.md。 - 格式化（如果可用）：
typstyle -i file.typ。僅在差異僅限於您自己的編輯時使用。 - 報告哪些檔案被建立/修改，以及如何重新建置。
最小骨架
#set document(title: "My Document", author: "Name")
#set page(paper: "a4", margin: 2.5cm, numbering: "1")
#set text(font: "New Computer Modern", size: 11pt, lang: "en")
#set par(justify: true, leading: 0.65em)
#set heading(numbering: "1.1")
#title()
= 引言 <intro>
Typst 支援 *粗體*、_斜體_、`原始`、數學 $E = m c^2$ 以及像 @intro 這樣的引用。
== 一個子章節
#lorem(30)
$ integral_0^1 x^2 dif x = 1/3 $
永遠安全的預設值：#set text(lang: "...")（斷詞、引號、補充、無障礙）、#set document(title: ...) + #title() 用於可見標題、#set par(justify: true) 用於正文。
60 秒語法速覽
| 模式 | 進入方式 | 範例 |
|---|---|---|
| 標記（預設） | — | = 標題、*粗體*、_斜體_、- 項目、+ 編號、/ 術語：描述、@標籤、<標籤> |
| 程式碼 | #（單一表達式）或 #{ ... } 區塊 | #let x = 3、#f(1)[主體]、#if a [是] else [否]、#for i in range(3) [#i ] |
| 數學 | $...$（$ x $ 含空格 = 顯示模式） | $a^2 + b_i$、$sum_(i=1)^n i$、$ vec(1, 2) $ |
| 內容區塊 | 在程式碼內使用 [...] | #box[嗨]、let c = [*x*] |
- 在程式碼內，不要重複
#：#figure(image("a.png"), caption: [嗨])。在[...]內容區塊內，你又回到了標記模式：[總數： #x]。 - 陣列
(1, 2)、字典(a: 1, b: 2)、空值()/(:)、單一元素(1,)。沒有 tuple。使用.at(i)索引，而不是[i]。 - 命名參數使用
:（f(width: 2cm)）；=僅在let/程式碼內為賦值。 - 字串
"..."、內容[...]、原始`...`。可使用str(x)、[#s]、eval(s, mode: "markup")進行轉換。 - 註解：
// 單行、/* 區塊 */。使用\跳脫特殊字元（\#、\$、\@、\*、\_、\<）；Unicode\u{1F600}。 - 長度單位：
pt mm cm in em、fr（分數）、%、角度deg rad。auto和none是值。 set= 從此處開始為元素設定預設參數；show= 重新設定樣式/取代元素。需要context才能讀取樣式/計數器/位置（請參閱references/introspection.md）。- 路徑：僅使用正斜線（0.15）。
"/x.typ"是相對於專案根目錄（預設根目錄：主檔案所在目錄；可使用--root變更），"x.typ"是相對於當前檔案。 - 處處可使用方法語法：
"abc".len()、(1,2,3).map(x => x*2)、rgb("#f00").lighten(30%)。
參考指南
| 需求 | 請閱讀 |
|---|---|
語法、型別、運算子、字串/陣列/字典方法、模組、閉包、context 基礎 | references/syntax-and-scripting.md |
set/show 規則、選擇器、頁面設定、文字、段落、區塊、網格、欄位、對齊、間距、定位、變換 | references/styling-and-layout.md |
| 標題、列表、圖表、表格、參考文獻、腳註、大綱、引文、參考文獻/引用/CSL、編號、連結、中繼資料 | references/document-model.md |
| 方程式、數學語法、符號、矩陣、對齊、字型、編號 | references/math.md |
| 形狀、曲線、圖片、顏色、漸層、平鋪、筆觸、特別色 | references/visuals.md |
計數器、狀態、query、locate、metadata、within、版面收斂、執行中頁首、measure/layout | references/introspection.md |
CSV/JSON/YAML/TOML/XML/CBOR、read、bytes、sys.inputs、eval、WASM 插件、資料驅動文件 | references/data-and-io.md |
CLI 旗標、字型、PDF/A/UA、無障礙、HTML、打包、PNG/SVG、typst eval、CI/可重複建置 | references/export-and-cli.md |
| 簡報（Touying/Polylux、動畫、講義、備註、pdfpc） | references/slides.md |
模板、typst.toml、發布套件、Universe 套件推薦（cetz, fletcher, touying, codly, ...）、編輯器工具 | references/templates-and-packages.md、references/packages-and-ecosystem.md |
| LaTeX → Typst 轉換、Markdown/pandoc 轉換、從 0.11–0.14 升級 | references/migration.md |
| 錯誤、警告、測試、視覺驗證、效能、常見陷阱 | references/pitfalls-and-debugging.md |
| 每個元素的確切參數/預設值（經 0.15.1 原始碼驗證） | references/api-signatures.md |
| 可直接編譯的入門範例 | examples/*.typ |
主要陷阱（寫程式碼前先閱讀）
- Set/show 規則僅向前作用且僅在其作用域內；將它們放在應受影響的內容之前。
[...]/{...}內部的set會隨區塊結束而終止。 - 讀取任何依賴位置/樣式的東西都需要
context：#context counter(page).get()、#context text.size。沒有它會出現：「only be used when context is known」。 - 被閉包捕獲的變數是唯讀複本；需透過
fold、單一程式碼區塊內的迴圈、state或counter來累積。 #只需要一次；對於標記中包含運算子的表達式使用#(a + b)；#f(x).g可以運作，但#f (x)（含空格）不會執行函式呼叫。- 數學不是文字：多字母單詞是符號/變數（
alpha、sin）；應將文字寫為"text"或upright(...)。單個字母是斜體變數。 - 字串不是內容：標題主體是內容；請使用
.body、str()或輔助函式to-string（請參閱語法參考）來取得文字。 - 字型：僅已安裝/內嵌/
--font-path指定的字型有效；未知字型系列僅會發出警告並使用後備字型。使用typst fonts列出。對於可變字型，請在名稱中省略「Variable」/「VF」（0.15）。 - 套件使用確切版本匯入：
#import "@preview/cetz:0.5.3"— 請查閱 Typst Universe 的最新版本（scripts/search-packages.py），不要依賴記憶。套件可能落後於新編譯器。 - 0.15 移除項目：
path()→curve()、pattern→tiling、pdf.embed→pdf.attach、*.decode(...)→ 傳遞bytes給json(...)等、typst query→typst eval、路徑中不再允許反斜線。 - HTML/打包匯出是實驗性的，需要
--features html/--features bundle。
快速慣用語
// 可重複使用的模板：使用函式的 show 規則
#let conf(title: none, authors: (), body) = {
set page(margin: 2cm)
set par(justify: true)
align(center, text(17pt, weight: "bold", title))
v(1em)
body
}
#show: conf.with(title: [我的論文])
// 為單一標題層級設定樣式
#show heading.where(level: 1): set text(navy)
#show heading.where(level: 1): it => block(above: 1.5em, below: 1em, it)
// 交叉引用與圖表
#figure(table(columns: 2, [A], [B], [1], [2]), caption: [數據]) <tab:data>
請參閱 @tab:data。
// 資料驅動內容
#for (name, score) in (("Ann", 3), ("Bo", 5)) [- #name：#score]
// 從 CLI 取得執行時期輸入：typst compile --input mode=draft main.typ
#let draft = sys.inputs.at("mode", default: "final") == "draft"
編譯速查表
typst compile main.typ # → main.pdf
typst compile main.typ out.pdf --root .
typst compile main.typ 'page-{0p}.png' --ppi 144
typst watch main.typ # 變更時重新編譯
typst eval 'calc.pow(2, 10)' # 評估表達式，輸出 JSON
typst eval --in main.typ 'query(heading).len()'
typst init @preview/charged-ieee # 從模板建立新專案
typst fonts --variants # 列出已安裝字型
範例（全部可在 0.15.1 上編譯）
| 檔案 | 展示內容 |
|---|---|
examples/memo.typ | 簡短備忘錄、表頭網格、簡單樣式 |
examples/report.typ | 標題頁、目錄、執行中頁首、圖表/表格/腳註、show 規則 |
examples/academic-paper.typ (+ refs.bib) | 方程式、定理環境、交叉引用、引用 |
examples/data-report.typ (+ data.csv) | CSV → 表格、計算欄位、--input、純形狀長條圖 |
examples/template.typ + template-usage.typ | 可重複使用的模板函式 + 元件 |
examples/accessible.typ | PDF/A-2a + PDF/UA-1（--pdf-standard a-2a,ua-1） |
examples/dual-target.typ | 單一來源 → PDF 和 HTML（context target()、html.*） |
examples/query-export.typ | metadata + typst eval 結構匯出 |
examples/slides-plain.typ、examples/letter.typ | 無套件簡報與正式信函 |
examples/packages-demo.typ | cetz、fletcher、lilaq、theorion、codly（固定版本，經驗證） |
腳本
scripts/check-snippets.py FILE.md…— 編譯每個```typ區塊（使用```typ-x表示說明性/不可編譯的區塊）。在你撰寫的任何包含 Typst 的 Markdown 檔案上執行它。scripts/search-packages.py "關鍵字" [--category cv] [--name cetz --versions]— 查詢 Typst Universe 索引以取得當前套件名稱/版本。