跳到內容
Oleaflyv0.4.12

為每個專案鎖定 Typst 版本、從 Typst Universe 加入套件、控制字型、建置變體與可重現的 PDF,並把 LaTeX 專案轉換為 Typst。

Oleafly 隨附 Typst 0.15.1 與 Tinymist 0.15.8 語言伺服器,所以新的 Typst 專案不必安裝任何東西就能編譯。本頁說明你可以更改的部分:專案使用哪個 Typst、套件與字型從哪裡來,以及同一份原始碼如何建置出多份 PDF。關於語法與工具列,請先閱讀用 Typst 寫作。

開啟 「設定 → 引擎 → Typst」。第一張卡片是 「Typst(內建)」,也就是隨應用程式提供的版本。如果你的電腦上已經安裝了 typst,不論是在 PATH 中、Homebrew 的資料夾,還是 ~/.cargo/bin,第二張卡片就會把它顯示為 「這台電腦上的 Typst」。鎖定該確切版本的專案,可以用它編譯。

卡片下方,「版本」 列出 Typst 0.11 到 0.15,最新的在前。每一列會顯示發布日期、下載大小、副本的來源(「內建」、「已下載」 或 「系統」),以及安裝之後它所使用的 Tinymist 版本。

  • 「安裝」 會下載該版本。Oleafly 會先試自己的鏡像,再試 GitHub,並以內建在應用程式中的 SHA-256 檢查碼,核對壓縮檔與其中的程式。不符的檔案會被丟棄,失敗或取消的安裝不會留下任何東西。下載的檔案放在 ~/.oleafly/toolchains/typst/。
  • 已安裝那一列左側的圓形按鈕,會把該版本設為預設。
  • 「移除」 會刪除已下載的版本。預設版本無法移除,所以請先選擇另一個預設版本。

新的 Typst 專案會鎖定預設版本。從範本建立的專案、匯入的專案與已連結資料夾也一樣。鎖定值以版本號碼(不是路徑)的形式存在專案的 project.json 中,所以在你搬移專案,或在另一台電腦上開啟時,仍然有效。

之後更改預設版本,不會連動既有的專案。這是刻意的:Oleafly 隨附較新的 Typst 時,已鎖定的論文仍保持相同的換行與頁數。

若要更改單一專案的版本,請開啟 「重新編譯」 旁邊的箭頭,並看 「Typst 版本(本專案)」 底下的內容。「預設」 會跟隨設定中選擇的版本,並清除鎖定。其他項目是這台電腦上已安裝的版本,適用時會標示 [內建] 或 [系統]。若要使用未列出的版本,請先在設定中安裝它。

如果你開啟的專案鎖定了這台電腦沒有的版本,Oleafly 不會悄悄改用不同的 Typst 來建置。編譯會停下來並顯示「未安裝 Typst 0.13.1」,預覽則提供兩個按鈕:

  • 「下載 Typst 0.13.1」 會安裝鎖定的版本並重新編譯。當該版本是 Oleafly 提供的版本時才會出現。
  • 「使用 Typst 0.15.1」(以你的預設版本命名)會清除鎖定,並用預設版本重新編譯。

在你選擇其中一個之前,編譯選單會把該鎖定標示為 [未安裝]。

開啟 Typst 專案時,只要安裝了較新的 Typst,設定中的 Typst 分頁就會顯示 「試用較新版本」。選擇 「以 Typst 0.15.1 檢查」(或它所指名的任何版本)。Oleafly 會在暫存資料夾中建置專案兩次,一次用專案目前的版本,一次用較新的版本。你的專案不會有任何變動。

報告會顯示每次建置是否成功、頁數,以及錯誤與警告。頁數有變動時,它會告訴你。「Typst 0.15.1 新增」 列出只有較新版本才會回報的訊息,「Typst 0.15.1 不再回報」 則列出會消失的訊息。點擊訊息,就能在該行開啟它的檔案。

如果你滿意所見,「切換到 Typst 0.15.1」 會把專案鎖定到較新的版本。「重新檢查」 會在你修正問題之後,重新執行兩次建置。

Tinymist 為 Typst 檔案提供自動完成、懸停說明、重新命名與格式化(參閱程式碼智慧)。每個 Typst 次要版本都有自己的 Tinymist 版本,專案會與符合其 Typst 版本的那一個溝通。

內建的 Tinymist 涵蓋 Typst 0.15。當你開啟鎖定在較舊系列的專案時,Oleafly 會在背景下載對應的 Tinymist,並做同樣的檢查碼驗證,狀態會顯示「正在下載 Tinymist 0.13.30,以配合此專案的 Typst 版本。」如果下載失敗,Oleafly 之後會再試。當設定發現有已不再被任何已安裝 Typst 需要的 Tinymist 下載時,會提供 「移除未使用的語言伺服器下載」。

保留較舊的版本,是為了讓以它們開始的專案能以相同的方式持續建置。有些功能取決於 Typst 版本本身支援什麼:

功能0.110.120.130.14 及更新版本
僅限專案字型否是是是
可重現建置否是是是
PNG 與 SVG 匯出的頁面範圍否是是是
PDF/A否PDF/A-2bPDF/A-2b、PDF/A-3bTypst 提供的所有 PDF/A 等級
PDF/UA-1否否否是
保留在專案資料夾中的套件否是是是
HTML 匯出,以及透過 Typst 的 HTML 進行的 Word 或 Markdown 匯出否否是是
原始碼與 PDF 同步否否是是
每次編譯都產生標記式 PDF否否否是

在 Typst 0.15 及更新版本上,字型選擇器能說明每個字型的來源。當某個設定無法套用到專案所用的版本時,編譯選單會把它標示為 「需要較新的 Typst」。

選擇 「Typst 套件」,也就是 Typst 工具列最右端的套件圖示。依名稱、關鍵字或類別搜尋 Typst Universe。每個套件都會顯示它的最新版本;需要比專案所用更新的 Typst 的套件會註明:「需要 Typst 0.14.0。此專案使用 Typst 0.13.1。」

「插入 import」 會把 #import 行寫在開啟的 Typst 檔案頂端。「複製 import」 則改為把它放到剪貼簿。

Typst 會在編譯第一次匯入 @preview 套件時下載它,並保存在所有專案共用的快取中。套件清單也會快取。離線時,對話方塊會顯示它上次取得的清單及其日期。

當 import 指定的版本比 Typst Universe 上的舊時,它的版本號碼會加上底線,並附上類似「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 會在四個地方尋找字型:Typst 內建的字型、你電腦上安裝的字型、你在 Oleafly 中下載的字型套件,以及專案內的字型資料夾。把字型檔案放在專案最上層名為 fonts 的資料夾中,編譯器與語言伺服器就都會讀取。額外的資料夾可以列在 project.json 的 typst.font_paths 底下。專案之外的資料夾會被忽略。

在編譯選單的 「字型(本專案)」 底下,「使用系統字型」 是預設值。「僅限專案字型」 會讓 Typst 不再讀取這台電腦上安裝的字型。這樣一來,PDF 在每台機器上都會一致;而且如果文件要求專案不包含的字型,你會在自己的電腦上發現,而不是在共同作者的電腦上。

若要選擇內文字型,請開啟 「文件設定」(Typst 工具列上的滑桿圖示),然後點擊 「內文字型」。清單會依專案目前的字型設定,列出 Typst 找得到的每個字型家族。在 Typst 0.15 及更新版本上,每個字型家族都帶有 「專案」、「系統」、「字型套件」 或 「內建」 標籤。選一個並選擇 「套用」,Oleafly 就會把它寫進文件的 #set 規則。

「設定 → 下載 → 字型」 提供五個給 Typst 使用的免費字型套件:「中文、日文和韓文」、「經典內文」、「現代無襯線與襯線」、「程式碼」 和 「圖示與表情符號」。套件下載完成後,每個 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 讀取的一組有名稱的值。當同一份原始碼需要產生不同的 PDF 時,請使用變體,例如匿名審查版與定稿版,或帶浮水印的草稿。

每個值要做什麼,由文件決定。值一律以文字的形式送達:

#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 日。

當 PDF 必須符合檢查碼時,這就很重要,例如存放到典藏庫,或在 CI 中比對。它需要 Typst 0.12 或更新版本。開啟期間,「使用系統字型」 無法使用。「標準建置」 是預設值。

Typst 邊輸入邊編譯:每新增一行,PDF 中就會隨之出現。
Typst 邊輸入邊編譯:每新增一行,PDF 中就會隨之出現。 開啟完整螢幕截圖

在編譯選單中,把 「自動編譯」 設為 「開啟」。在 Typst 專案中,Oleafly 接著會讓一個 Typst 處理程序持續執行。你停止輸入片刻後,開啟的檔案會自動儲存,Typst 隨即編譯,預覽則在相同的捲動位置重新載入。沒有另外的即時預覽設定:自動編譯就是即時預覽。

Typst 啟動期間,選單會顯示「正在啟動 Typst」。如果它因重複出錯而停止,選單會告訴你,而你的下一次編輯會讓它重新啟動。「停止編譯」 會結束該處理程序,下一次編輯同樣會讓它重新啟動。LaTeX 與 Markdown 專案處理自動編譯的方式不同;請參閱編譯。

oleafly 指令可以在不開啟應用程式的情況下建置專案。它隨 Oleafly 提供,命令列工具說明如何把它放到你的 PATH 上。

對於 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 專案,按 ⌘K(Ctrl+K)並執行 「轉換為 Typst 專案」。為新專案命名並選擇 「轉換」。LaTeX 專案會維持原樣。Oleafly 會依它建立另一個獨立的 Typst 專案:

  • Pandoc 會轉換文字、數學式、圖片與表格。如果 Pandoc 尚未設定,Oleafly 會先設定它。
  • 以 \input、\include 或 \subfile 引入的每個檔案,都會成為獨立的 .typ 檔案。
  • BibTeX 檔案會原樣複製。
  • Typst 會編譯新專案來進行檢查。

接著報告會說明專案是否能編譯,並統計轉換了什麼:原始碼檔案、圖片、表格、行間公式、交互參照、數學轉換器修正的公式,以及複製的檔案,連同它選擇的參考文獻樣式。「需要處理」 會列出需要手動修正的項目,例如缺少的引入檔案或影像、Typst 無法顯示的影像格式、轉換器無法處理的數學式、沒有 Typst 對應的 BibTeX 樣式,或是多行公式其中一行上的標籤(它現在指向整個公式)。編譯錯誤與警告會連結到它們的檔案與行。

選擇 「開啟 Typst 專案」 以切換過去。新專案會鎖定你的預設 Typst 版本。只要 Oleafly 保持開啟,命令面板中的 「顯示 Typst 轉換報告」 就能把報告叫回來。

如果只想轉換單一檔案而不是整個專案,請在工具頁面使用 LaTeX 轉 Typst。

圖片預覽

無法載入 AI 回答

請再試一次,或搜尋文件。