# Dự án Typst

Ghim một phiên bản Typst cho từng dự án, thêm gói từ Typst Universe, kiểm soát phông chữ, biến thể bản dựng và PDF tái lập, rồi chuyển đổi một dự án LaTeX sang Typst.

Oleafly đi kèm Typst 0.15.1 và máy chủ ngôn ngữ Tinymist 0.15.8, nên một dự án Typst mới biên dịch được mà không cần cài thêm gì. Trang này nói về những gì bạn có thể thay đổi: dự án dùng Typst nào, gói và phông chữ của nó đến từ đâu, và làm thế nào một mã nguồn dựng ra nhiều hơn một PDF. Về cú pháp và thanh công cụ, hãy bắt đầu với [Viết bằng Typst](/docs/writing/typst/).

## Các phiên bản Typst

Mở **Settings → Engines → Typst**. Thẻ đầu tiên là **Typst (built in)**, phiên bản đi kèm với ứng dụng. Nếu một `typst` đã được cài trên máy của bạn, nằm trên `PATH`, trong thư mục của Homebrew hoặc trong `~/.cargo/bin`, một thẻ thứ hai hiển thị nó dưới tên **Typst on this computer**. Các dự án ghim chính xác phiên bản đó có thể biên dịch bằng nó.

Bên dưới là **Versions**, liệt kê Typst 0.11 đến 0.15, mới nhất trước. Mỗi dòng cho biết ngày phát hành, dung lượng tải về, bản sao đến từ đâu (**Built in**, **Downloaded** hoặc **System**) và, sau khi cài đặt, bản phát hành Tinymist mà nó dùng.

- **Install** tải về phiên bản đó. Oleafly thử mirror riêng của mình trước rồi GitHub sau, và đối chiếu tệp nén lẫn chương trình bên trong nó với các checksum SHA-256 được dựng sẵn vào ứng dụng. Một tệp không khớp sẽ bị vứt bỏ, và một lần cài thất bại hoặc bị hủy không để lại gì. Các bản tải về nằm trong `~/.oleafly/toolchains/typst/`.
- Nút tròn ở bên trái một dòng đã cài đặt đặt phiên bản đó làm mặc định.
- **Remove** xóa một phiên bản đã tải về. Phiên bản mặc định không thể bị xóa, nên hãy chọn một mặc định khác trước.

### Phiên bản mặc định và việc ghim phiên bản

Các dự án Typst mới ghim phiên bản mặc định. Các dự án tạo từ mẫu, dự án nhập vào và thư mục được liên kết cũng vậy. Việc ghim được lưu trong `project.json` của dự án dưới dạng một số phiên bản, chứ không phải một đường dẫn, nên nó vẫn dùng được sau khi bạn di chuyển dự án hoặc mở nó trên máy tính khác.

Thay đổi mặc định sau đó không kéo theo các dự án đã có. Điều đó là có chủ đích: một bài báo đã ghim giữ nguyên cách xuống dòng và số trang khi Oleafly phát hành một Typst mới hơn.

Để đổi phiên bản của một dự án, mở mũi tên bên cạnh **Recompile** và tìm dưới **Typst version (this project)**. **Default** theo phiên bản được chọn trong Settings và xóa việc ghim. Các mục khác là những phiên bản đã cài trên máy này, đánh dấu **[built in]** hoặc **[system]** khi áp dụng. Để dùng một phiên bản không có trong danh sách, hãy cài nó trong Settings trước.

### Khi phiên bản được ghim bị thiếu

Nếu bạn mở một dự án ghim một phiên bản mà máy này không có, Oleafly sẽ không âm thầm dựng nó bằng một Typst khác. Việc biên dịch dừng lại với thông báo "Typst 0.13.1 is not installed", và bản xem trước đưa ra hai nút:

- **Download Typst 0.13.1** cài phiên bản được ghim và biên dịch lại. Nút này xuất hiện khi phiên bản nằm trong số những phiên bản Oleafly cung cấp.
- **Use Typst 0.15.1**, đặt tên theo phiên bản mặc định của bạn, xóa việc ghim và biên dịch lại với phiên bản mặc định.

Menu biên dịch đánh dấu việc ghim là **[not installed]** cho đến khi bạn chọn một trong hai nút.

### Thử một phiên bản mới hơn trước khi chuyển

Với một dự án Typst đang mở, thẻ Typst trong Settings hiển thị **Try a newer version** bất cứ khi nào một Typst mới hơn đã được cài. Chọn **Check with Typst 0.15.1** (hoặc phiên bản nào nó nêu tên). Oleafly dựng dự án hai lần trong các thư mục tạm, một lần với phiên bản hiện tại của dự án và một lần với phiên bản mới hơn. Không gì trong dự án của bạn thay đổi.

Báo cáo cho biết mỗi bản dựng có thành công không, số trang, cùng lỗi và cảnh báo của nó. Nó cho bạn biết nếu số trang thay đổi. **New in Typst 0.15.1** liệt kê các thông báo mà chỉ phiên bản mới hơn đưa ra, còn **No longer reported by Typst 0.15.1** liệt kê những thông báo biến mất. Nhấp vào một thông báo để mở tệp của nó tại dòng đó.

Nếu bạn thích những gì thấy được, **Switch to Typst 0.15.1** ghim dự án vào phiên bản mới hơn. **Check again** chạy lại cả hai bản dựng sau khi bạn sửa gì đó.

### Máy chủ ngôn ngữ theo phiên bản

Tinymist dẫn dắt phần gợi ý hoàn thành, trợ giúp khi rê chuột, đổi tên và định dạng trong các tệp Typst (xem [Trí tuệ mã nguồn](/docs/code-intelligence/#typst-files)). Mỗi phiên bản phụ của Typst có bản phát hành Tinymist riêng, và một dự án nói chuyện với bản khớp với phiên bản Typst của nó.

Tinymist tích hợp sẵn bao phủ Typst 0.15. Khi bạn mở một dự án ghim vào một nhánh cũ hơn, Oleafly tải về bản Tinymist khớp ở nền sau, với cùng phép đối chiếu checksum, và trạng thái hiển thị "Downloading Tinymist 0.13.30 to match this project's Typst version." Nếu việc tải về thất bại, Oleafly thử lại sau. Khi Settings thấy các bản tải Tinymist mà không còn Typst nào đã cài cần đến, nó đưa ra **Remove unused language server downloads**.

### Mỗi phiên bản làm được gì

Các phiên bản cũ tồn tại để những dự án bắt đầu trên chúng cứ dựng theo cách cũ. Một số tính năng phụ thuộc vào việc chính phiên bản Typst hỗ trợ gì:

| Tính năng | 0.11 | 0.12 | 0.13 | 0.14 trở lên |
| --- | --- | --- | --- | --- |
| Project fonts only | Không | Có | Có | Có |
| Reproducible build | Không | Có | Có | Có |
| Khoảng trang khi xuất PNG và SVG | Không | Có | Có | Có |
| PDF/A | Không | PDF/A-2b | PDF/A-2b, PDF/A-3b | Mọi cấp độ PDF/A Typst cung cấp |
| PDF/UA-1 | Không | Không | Không | Có |
| Gói được giữ trong thư mục dự án | Không | Có | Có | Có |
| Xuất HTML, và xuất Word hoặc Markdown qua HTML của Typst | Không | Không | Có | Có |
| [Đồng bộ mã nguồn và PDF](/docs/synctex/) | Không | Không | Có | Có |
| PDF có gắn thẻ ở mỗi lần biên dịch | Không | Không | Không | Có |

Trình chọn phông chữ có thể cho biết mỗi phông chữ đến từ đâu trên Typst 0.15 trở lên. Khi một cài đặt không thể áp dụng cho phiên bản dự án đang dùng, menu biên dịch đánh dấu nó **Needs a newer Typst**.

## Gói từ Typst Universe

Chọn **Typst packages**, biểu tượng gói ở đầu bên phải của thanh công cụ Typst. Tìm trên Typst Universe theo tên, từ khóa hoặc danh mục. Mỗi gói hiển thị phiên bản mới nhất của nó, và một gói cần Typst mới hơn phiên bản dự án đang dùng sẽ nói rõ điều đó: "Needs Typst 0.14.0. This project uses Typst 0.13.1."

**Insert import** ghi dòng `#import` vào đầu tệp Typst đang mở. **Copy import** đặt nó vào bảng tạm thay vào đó.

Typst tải về một gói `@preview` ở lần đầu một lần biên dịch nhập nó và giữ nó trong một bộ nhớ đệm mà mọi dự án dùng chung. Danh sách gói cũng được lưu vào bộ nhớ đệm. Khi ngoại tuyến, hộp thoại hiển thị danh sách gần nhất nó đã lấy, kèm ngày tháng.

### Các bản phát hành mới hơn

Khi một lệnh nhập nêu một bản phát hành cũ hơn bản trên Typst Universe, số phiên bản của nó được gạch chân kèm một gợi ý như "cetz 0.4.2 is available. This import uses 0.3.4." Thẻ gợi ý đưa ra **Update to 0.4.2**, thay đổi số phiên bản trong lệnh nhập. Hãy đọc nhật ký thay đổi của gói trước khi chấp nhận, vì một bản phát hành mới có thể thay đổi cách gói được gọi. Rê chuột lên một lệnh nhập cũng đưa ra **Open on Typst Universe**.

### Giữ gói ngay trong dự án

Dưới **Project packages** trong cùng hộp thoại, **Vendor packages into project** sao chép mọi gói mà dự án nhập vào một thư mục `typst-packages` ở thư mục gốc của dự án. Nó cũng sao chép các gói mà chính những gói đó nhập, và bật **Use packages from the project folder**.

Từ đó trở đi Typst tìm trong `typst-packages` trước. Một dự án đã vendored biên dịch được khi ngoại tuyến và trên bất kỳ máy tính nào, và thư mục đó có thể đi vào Git cùng mã nguồn của bạn. Một gói bạn chưa vendored vẫn đến từ bộ nhớ đệm dùng chung. Việc này cần Typst 0.12 trở lên, và trên một dự án ghim 0.11, hộp thoại yêu cầu bạn chuyển phiên bản trước.

Nếu một gói chưa có trong bộ nhớ đệm, hộp thoại nêu tên nó: "These packages aren't in the package cache: …". Hãy biên dịch một lần khi trực tuyến, rồi mới vendored lại.

### Chế độ Offline

Khi **Offline mode** được bật trong **Settings → General**, Typst không thể tải bất cứ gì. Mọi gói phải đã có trong bộ nhớ đệm dùng chung hoặc trong `typst-packages`. Nếu thiếu một gói, việc biên dịch thất bại và thông điệp nêu tên gói, nhờ vậy bạn biết cần tải gì ở lần trực tuyến tiếp theo.

## Phông chữ

Typst tìm phông chữ ở bốn nơi: các phông chữ dựng sẵn trong Typst, các phông chữ cài trên máy của bạn, các gói phông chữ bạn tải trong Oleafly, và các thư mục phông chữ bên trong dự án. Đặt các tệp phông chữ vào một thư mục tên `fonts` ở thư mục gốc của dự án, thì cả trình biên dịch lẫn máy chủ ngôn ngữ đều nhận ra chúng. Các thư mục thêm có thể được liệt kê dưới `typst.font_paths` trong `project.json`. Thư mục nằm ngoài dự án bị bỏ qua.

Dưới **Fonts (this project)** trong menu biên dịch, **Use system fonts** là mặc định. **Project fonts only** khiến Typst không đọc các phông chữ cài trên máy này. PDF khi đó cho ra kết quả giống nhau trên mọi máy, và nếu tài liệu yêu cầu một phông chữ dự án không có, bạn phát hiện điều đó trên chính máy của mình thay vì trên máy của một đồng tác giả.

Để chọn phông chữ phần thân, mở **Document settings**, biểu tượng thanh trượt trên thanh công cụ Typst, rồi nhấp **Body font**. Danh sách hiển thị mọi họ phông chữ Typst tìm được với cài đặt phông chữ hiện tại của dự án. Trên Typst 0.15 trở lên, mỗi họ mang một nhãn **Project**, **System**, **Font pack** hoặc **Built in**. Chọn một họ rồi chọn **Apply**, Oleafly ghi nó vào các quy tắc `#set` của tài liệu.

### Gói phông chữ

**Settings → Downloads → Fonts** có năm gói phông chữ miễn phí cho Typst: **Chinese, Japanese and Korean**, **Classic text**, **Modern sans and serif**, **Code**, và **Icons and emoji**. Sau khi một gói đã tải xong, mọi dự án Typst đều dùng được phông chữ của nó theo tên, và điều tương tự áp dụng cho các bản tải Lato, PT Sans và PT Serif trên tab đó. Một gói chỉ tham gia các lần biên dịch sau khi toàn bộ lượt tải đã hoàn tất, nên một lượt tải dở dang không bao giờ ảnh hưởng đến bản dựng.

Các dự án đặt **Project fonts only** hoặc **Reproducible build** không đọc gói phông chữ. Với những dự án đó, hãy sao chép tệp phông chữ vào thư mục `fonts` của dự án.

### Ký tự hiện thành ô vuông

Sau mỗi lần biên dịch, Oleafly kiểm tra những ký tự mà không phông chữ nào có sẵn vẽ được. Typst vẽ chúng thành ô vuông. Khi tìm thấy, lần biên dịch nhận một cảnh báo và một thông báo hiện phía trên trình soạn thảo:

- **Ô vuông trống** nghĩa là không phông chữ nào Typst dùng được có các ký tự đó, và cảnh báo nêu tên vài ký tự. Khi một gói phông chữ bao phủ chúng, như gói Chinese, Japanese and Korean làm với văn bản CJK và gói Icons and emoji làm với emoji, thông báo đề xuất **Download fonts** kèm dung lượng tải, và nhật ký đề xuất **Download and compile**. Nếu không, hãy thêm một phông chữ có chúng vào thư mục `fonts` của dự án.
- **Ô vuông có dấu hỏi** nghĩa là Typst đã vẽ các ký tự bằng một phông chữ giữ chỗ. Nêu tên một phông chữ có chúng dưới **Body font** trong **Document settings**, hoặc trong một danh sách phông chữ như `#set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))`.
- Trong một dự án đặt **Project fonts only**, gói phông chữ và phông chữ hệ thống không áp dụng. Thêm một phông chữ vào thư mục `fonts`, hoặc chuyển dự án sang **Use system fonts** và **Standard build**.

**Document settings** trong thông báo mở bảng nơi bạn chọn phông chữ phần thân. Đóng thông báo để ẩn nó cho cảnh báo đó.

## Biến thể bản dựng và sys.inputs

Một biến thể bản dựng là một bộ giá trị có tên mà tài liệu của bạn đọc qua `sys.inputs`. Dùng biến thể khi một mã nguồn cần tạo ra các PDF khác nhau, chẳng hạn một bản gửi đánh giá ẩn danh và một bản camera-ready, hoặc một bản nháp có hình mờ.

Tài liệu quyết định mỗi giá trị làm gì. Các giá trị luôn đến dưới dạng văn bản:

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

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

Để thiết lập một biến thể:

1. Mở **Document settings** và cuộn đến **Build variants**.
2. Chọn **Add variant** và đặt tên, ví dụ `review`.
3. Chọn **Add value**, rồi nhập `draft` dưới **Name** và `true` dưới **Value**.
4. Chọn **Apply**.
5. Mở menu biên dịch. **Variant (this project)** giờ liệt kê `review`. Chọn nó và biên dịch.

**No variant** dựng mà không có giá trị biến thể nào. Biến thể bạn chọn chỉ được ghi nhớ trên máy này, nên một đồng tác giả có thể dựng một biến thể khác từ cùng dự án. Bản thân các biến thể được lưu trong `project.json`. Việc xuất cũng dùng biến thể đang được chọn.

Các giá trị mà mọi bản dựng đều nên nhận nằm dưới `typst.inputs` trong `project.json`. Khi một biến thể đặt một giá trị trùng tên, biến thể thắng.

## Bản dựng tái lập

Dưới **Build (this project)** trong menu biên dịch, **Reproducible build** làm cho cùng một mã nguồn cho ra cùng một PDF trên bất kỳ máy tính nào. Nó chỉ dùng các phông chữ của dự án và phông chữ dựng sẵn của Typst, và ghi ngày cho PDF theo commit Git cuối cùng. Một dự án không phải kho Git nhận một ngày cố định là 1 tháng 1 năm 1970.

Điều này quan trọng khi một PDF phải khớp một checksum, cho một lần nộp lưu trữ hoặc một phép so sánh trong CI. Nó cần Typst 0.12 trở lên. Khi nó đang bật, **Use system fonts** không dùng được. **Standard build** là mặc định.

![Typst biên dịch ngay khi bạn gõ: mỗi dòng mới xuất hiện trong PDF.](https://cdn.oleafly.com/images/gifs/desktop/typst-live.gif?v=2)

## Bản xem trước trực tiếp với Auto compile

Đặt **Auto compile** thành **On** trong menu biên dịch. Trong một dự án Typst, Oleafly khi đó giữ một tiến trình Typst chạy liên tục. Tệp đang mở tự lưu một lúc sau khi bạn ngừng gõ, Typst biên dịch nó, và bản xem trước tải lại tại cùng vị trí cuộn. Không có một cài đặt bản xem trước trực tiếp riêng biệt: Auto compile chính là bản xem trước trực tiếp.

Trong lúc Typst khởi động, menu hiển thị "Starting Typst". Nếu nó dừng sau nhiều lỗi lặp lại, menu nói rõ điều đó, và lần chỉnh sửa tiếp theo của bạn khởi động lại nó. **Stop compilation** kết thúc tiến trình, và lần chỉnh sửa tiếp theo cũng khởi động lại nó. Các dự án LaTeX và Markdown xử lý Auto compile khác đi; xem [Biên dịch](/docs/compiling/#auto-compile).

## Dựng từ dòng lệnh

Lệnh `oleafly` dựng các dự án mà không cần mở ứng dụng. Nó đi kèm Oleafly, và [Công cụ dòng lệnh](/docs/cli/#install) cho biết cách đặt nó lên PATH của bạn.

Với một dự án Typst, `oleafly build` và `oleafly watch` đọc `project.json` và dùng cùng cài đặt như ứng dụng: phiên bản được ghim, các gói đã vendored, các thư mục phông chữ, công tắc phông chữ hệ thống, inputs và bản dựng tái lập.

- `--variant review` dựng một biến thể. Một tên dự án không định nghĩa làm việc dựng dừng lại, và thông điệp liệt kê các biến thể mà dự án có.
- `--offline` chặn việc tải gói, giống Offline mode trong ứng dụng.
- Một dự án đã ghim chỉ dựng với chính xác Typst đó. CLI nhìn vào `OLEAFLY_TYPST`, rồi các phiên bản ứng dụng đã tải về, rồi `typst` nằm cạnh CLI, rồi `PATH` của bạn. Nếu không cái nào báo phiên bản được ghim, việc dựng dừng trước khi Typst chạy và cho bạn biết cách cài nó.
- Một dự án không ghim dùng `OLEAFLY_TYPST` khi biến này được đặt. Nếu không, nó dùng phiên bản mặc định bạn chọn trong **Settings → Downloads** hoặc bằng `oleafly typst default`, và khi chưa chọn mặc định nào, dùng Typst đi kèm hoặc Typst trên `PATH` của bạn.
- `oleafly doctor` liệt kê mọi Typst nó tìm thấy và các cài đặt mà một bản dựng sẽ dùng. Nó thất bại khi phiên bản được ghim bị thiếu.

Nếu một cài đặt không thể áp dụng cho Typst đang dùng, bản dựng in ra một ghi chú, ví dụ rằng Typst 0.11.1 không thể bỏ qua phông chữ hệ thống. Các lỗi trong terminal bao gồm cả gợi ý riêng của Typst.

## Chuyển đổi một dự án LaTeX sang Typst

Mở dự án LaTeX, nhấn ⌘K (Ctrl+K) và chạy **Convert to a Typst project**. Đặt tên cho dự án mới và chọn **Convert**. Dự án LaTeX giữ nguyên như cũ. Oleafly dựng từ nó một dự án Typst riêng biệt:

- Pandoc chuyển đổi văn bản, công thức, hình vẽ và bảng. Nếu Pandoc chưa được thiết lập, Oleafly thiết lập nó trước.
- Mỗi tệp được đưa vào bằng `\input`, `\include` hoặc `\subfile` trở thành một tệp `.typ` riêng.
- Các tệp BibTeX được sao chép nguyên trạng.
- Typst biên dịch dự án mới để kiểm tra nó.

Báo cáo khi đó cho biết dự án có biên dịch được không và đếm những gì đã được chuyển đổi: các tệp nguồn, hình vẽ, bảng, công thức trình bày, tham chiếu chéo, các công thức bộ chuyển đổi toán đã sửa, và các tệp được sao chép, cùng kiểu tài liệu tham khảo nó chọn. **Needs attention** liệt kê những gì phải sửa tay, chẳng hạn một lệnh include hay hình bị thiếu, một định dạng hình Typst không hiển thị được, công thức bộ chuyển đổi không xử lý nổi, một kiểu BibTeX không có bản Typst tương ứng, hoặc một nhãn nằm trên một dòng của một công thức nhiều dòng, mà giờ trỏ vào cả công thức. Các lỗi và cảnh báo biên dịch liên kết đến tệp và dòng của chúng.

Chọn **Open the Typst project** để chuyển sang nó. Dự án mới ghim phiên bản Typst mặc định của bạn. Trong khi Oleafly còn mở, **Show the Typst conversion report** trong bảng lệnh đưa báo cáo trở lại.

Để chuyển đổi một tệp đơn lẻ thay vì cả một dự án, hãy dùng [LaTeX to Typst](/docs/tools/latex-to-typst/) trên trang Tools.

## Các trang liên quan

- [Viết bằng Typst](/docs/writing/typst/) về thanh công cụ và một tài liệu đầu tiên.
- [Biên dịch](/docs/compiling/) về nhật ký, menu biên dịch và chế độ Offline.
- [Xuất và chuyển đổi dự án](/docs/export/#typst-images-and-html) về PNG, SVG, HTML, PDF/A và PDF/UA.
- [Các kiểm tra Preflight](/docs/preflight/#typst-projects) về các phép kiểm tra đọc mã nguồn Typst.
