Viết bằng Typst

Chọn một mẫu Typst và chỉnh sửa tệp nguồn .typ của nó ngay bên cạnh tệp PDF đã biên dịch. Thanh công cụ viết cú pháp Typst giúp bạn, nên mọi thay đổi đều nằm trong tệp nguồn, nơi bạn có thể đọc và chỉnh sửa chúng. Khi bạn không muốn nhìn vào mã đánh dấu, hãy chuyển tệp sang chế độ Visual.

Ví dụ Typst với thanh công cụ định dạng, tệp nguồn và báo cáo đã biên dịch. Mở ảnh chụp màn hình đầy đủ

Biên dịch một báo cáo nhỏ

1. Chọn New project → Use a template → Blank Typst document.
2. Đặt tên là Ghi chú đo lường và mở main.typ.
3. Dán ví dụ dưới đây vào, rồi chọn Recompile hoặc nhấn ⌘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],
)

Tệp PDF sẽ hiển thị các tiêu đề có đánh số, một phương trình dạng hiển thị, một tham chiếu đến phần phương pháp và một bảng hai cột.

Để xem tệp PDF thay đổi trong lúc bạn gõ, hãy mở mũi tên bên cạnh Recompile và đặt Auto compile thành On. Trong một dự án Typst, đó chính là bản xem trước trực tiếp. Xem Bản xem trước trực tiếp với Auto compile.

Tải xuống tệp nguồn ví dụ

Mọi công cụ trên thanh công cụ

Hãy chọn văn bản trước khi dùng một công cụ định dạng để bọc văn bản đó. Khi không có gì được chọn, thanh công cụ sẽ chèn một vùng giữ chỗ để bạn gõ đè lên. Khi trình soạn thảo quá hẹp không đủ chỗ cho mọi nút, những nút không vừa sẽ chuyển vào More formatting options (…). Hầu hết các công cụ này cũng có trong menu chuột phải của trình soạn thảo.

Code / Visual

Công tắc ở đầu thanh công cụ thay đổi cách tệp được hiển thị. Code hiển thị tệp nguồn Typst. Visual vẽ các tiêu đề, phần nhấn mạnh, danh sách, công thức toán, hình ảnh, bảng biểu, tham chiếu và chú thích cuối trang ngay tại chỗ, và đưa tệp nguồn trở lại trên dòng có con trỏ của bạn. Tệp giống nhau ở cả hai chế độ. Chế độ Visual trong Typst có mọi chi tiết.

Undo

Hoàn tác chỉnh sửa gần nhất của bạn. ⌘Z / Ctrl+Z. Nút chuyển sang màu xám khi không còn gì để hoàn tác.

Redo

Áp dụng lại một chỉnh sửa đã hoàn tác. ⌘Shift+Z / Ctrl+Shift+Z.

Heading → Title

Chọn một đoạn làm tiêu đề rồi chọn Title. = Title.

Heading → Section

Thêm một mục trong tài liệu. == Section.

Heading → Subsection

Thêm một cấp nằm dưới mục. === Subsection.

Heading → Subsubsection

Thêm một tiêu đề cấp bốn. ==== Subsubsection.

Heading → Minor heading

Thêm một tiêu đề cấp năm. ===== Minor heading.

Heading → Paragraph heading

Thêm một tiêu đề cấp sáu. ====== Paragraph heading.

Bold

Chọn “three observations”. *three observations*; ⌘B / Ctrl+B.

Italic

Chọn một thuật ngữ cần nhấn mạnh. _term_; ⌘I / Ctrl+I.

Underline

Chọn một cụm từ. #underline[phrase].

Strikethrough

Đánh dấu một cụm từ đã lỗi thời. #strike[phrase].

Inline code

Chọn một tên tệp hoặc tên biến. Công cụ bọc nó bằng dấu backtick.

Insert link

Thay url, rồi đến text. #link("url")[text].

Cite from project

Tìm trong tài liệu tham khảo của dự án theo khóa, tác giả hoặc tiêu đề, rồi chọn một mục. Oleafly ghi @key. Nếu tài liệu chưa có lệnh #bibliography nào, Oleafly sẽ thêm vào. Find and add a new citation… ở cuối danh sách mở phần tìm kiếm nguồn mới. Xem Thêm trích dẫn.

Insert cross-reference

Chọn một nhãn từ danh sách của dự án để ghi @label. Trong ví dụ, chọn method để được @method. Add a label here thì đặt một nhãn mới lên phần tử tại vị trí con trỏ.

Add label

Đặt con trỏ vào một tiêu đề, hình hoặc phương trình rồi chọn Add label. Trên tiêu đề Results trong ví dụ, Oleafly thêm <sec:results>. Nếu phần tử đã có nhãn, nút này sẽ chọn nhãn đó.

Insert footnote

Đặt con trỏ sau một từ. #footnote[note text].

Insert blockquote

Đặt con trỏ trên một dòng mới. #quote(block: true)[quote].

Insert figure

Mở hộp thoại hình. Chọn một hình ảnh từ Project images hoặc chọn Import from disk…, rồi đặt chiều rộng, chú thích, nhãn, văn bản thay thế và vị trí đặt hình. Khi con trỏ nằm trong một #figure sẵn có, chính nút đó sẽ mở Edit figure để bạn thay đổi bất kỳ mục nào trong số đó. Xem Thêm hình có chú thích.

Insert table

Mở lưới và chọn số hàng và số cột. Oleafly chèn một #figure chứa table với một hàng tiêu đề và các đường kẻ trên, giữa, dưới, kèm theo caption: [Caption] và nhãn <tab:label>. Hãy thay chú thích, nhãn và các ô trống. Còn để dựng bảng từ tệp bảng tính, xem Bảng từ tệp dữ liệu.

Insert image

Nhập một hình ảnh, rồi thay tên tệp được chọn bằng đường dẫn tương đối của nó. #image("image-filename"). Bạn cũng có thể dán hoặc kéo thả một tệp hình ảnh vào trình soạn thảo, và Oleafly sẽ lưu nó vào dự án rồi chèn một hình dùng tệp đó.

Draw a diagram

Mở trình soạn sơ đồ ở chế độ Typst. Vẽ trên vùng vẽ hoặc chỉnh sửa mã fletcher, rồi chọn Insert as Typst để đặt sơ đồ tại con trỏ. Lần xem trước đầu tiên sẽ tải gói fletcher từ Typst Universe, nên bạn cần kết nối mạng.

Image to Typst

Chọn một ảnh chụp màn hình của một phương trình hoặc một đoạn văn, và nó sẽ được chuyển thành Typst tại con trỏ. Nút này dùng mô hình cho Tools, là một mô hình Ollama cục bộ trừ khi bạn chọn mô hình khác. Nếu bạn chưa chọn mô hình nào và Ollama không chạy hoặc không có mô hình đọc được ảnh, nút sẽ dùng mô hình của trợ lý, và ảnh sẽ được gửi đến nhà cung cấp đó. Hãy kiểm tra kết quả rồi biên dịch.

List → Bulleted list

Bắt đầu một danh sách các quan sát. - Item.

List → Numbered list

Bắt đầu một chuỗi các bước. + Item.

Math

Chọn x và nhấn biểu tượng toán. $x$.

Display equation

Một phương trình nằm trên dòng riêng của nó. $ x $, với một khoảng trắng bên trong mỗi dấu $.

Numbered equation

Một phương trình dạng hiển thị có nhãn, chẳng hạn $ x $ <eq:label>. Typst chỉ đánh số phương trình khi tài liệu có quy tắc đánh số. Nếu tài liệu của bạn chưa có, một ghi chú sẽ đề xuất Add rule, vốn thêm #set math.equation(numbering: "(1)") gần đầu tệp.

Aligned equations

Một vài phương trình căn chỉnh tại &, với \ giữa các hàng. $ a &= b \ c &= d $.

Fraction

Chèn frac(a, b), được bọc trong $ khi con trỏ chưa nằm trong vùng toán. Khi có văn bản được chọn, phần được chọn sẽ thành tử số.

Symbols

Mở bảng chọn ký hiệu, tìm một ký hiệu rồi chọn nó. Oleafly ghi ký hiệu theo tên Typst của nó: arrow.r trong công thức toán, hoặc #sym.arrow.r trong văn bản thường.

Code block

Chọn một vài dòng mã hoặc thay vùng giữ chỗ. Một khối được bao bởi ba dấu backtick. Thêm ngôn ngữ sau dòng mở khối để được tô màu cú pháp.

Code intelligence → Go to definition

Đặt con trỏ vào một nhãn, biến hoặc hàm rồi chọn hành động, hoặc nhấn F12. Mở ngay nơi nó được định nghĩa, kể cả trong tệp khác.

Code intelligence → Find references

Liệt kê mọi nơi một nhãn, biến hoặc hàm được dùng. ⇧F12.

Code intelligence → Rename symbol

Đổi tên một nhãn, biến hoặc hàm trong toàn dự án. F2. Code intelligence đề cập cả ba chức năng.

Typst packages

Biểu tượng gói ở đầu bên phải thanh công cụ tìm kiếm trên Typst Universe và chèn một dòng #import. Xem thêm tại Gói, cài đặt và thông tin chi tiết.

Document insights

Liệt kê các tiêu đề, hình, bảng, phương trình, nhãn, trích dẫn và việc cần làm của tài liệu, mỗi mục có liên kết đến dòng của nó. Xem Document insights.

Document settings

Thay đổi khổ giấy, lề, phông chữ, ngôn ngữ, căn lề hai bên, khoảng cách dòng và cách đánh số bằng cách chỉnh các quy tắc #set của tài liệu. Xem Document settings.

Project info

Hiển thị số từ, số hình và số công thức của tài liệu và của bất kỳ phần nào được chọn, cùng kết quả soát lỗi.

Find

Tìm một từ trong tệp đang mở. ⌘F / Ctrl+F.

Go to PDF

Nhảy từ con trỏ đến vị trí tương ứng trong tệp PDF đã biên dịch. Nút xuất hiện từ Typst 0.13 trở đi. Xem Nhảy giữa tệp nguồn và tệp PDF.

Chế độ Visual

Chuyển thanh công cụ từ Code sang Visual trong bất kỳ tệp .typ nào. Chế độ Visual là chính trình soạn thảo ấy nhưng với mã đánh dấu được vẽ tại chỗ:

• tiêu đề, chữ đậm và chữ nghiêng, văn bản thô, liên kết và chữ màu
• danh sách gạch đầu dòng, danh sách đánh số và danh sách thuật ngữ cùng dấu đầu dòng của chúng
• công thức toán trong dòng và công thức dạng hiển thị, do Typst vẽ
• hình ảnh và các hình minh họa, với chú thích hiện dạng văn bản
• bảng dưới dạng lưới để bạn gõ vào. Chọn một ô để có thanh công cụ nhỏ cho viền, căn chỉnh, hàng và cột.
• tham chiếu và trích dẫn dạng chip, chú thích cuối trang thành một ký hiệu nhỏ

Đặt con trỏ lên một dòng và mã nguồn của dòng đó hiện trở lại để bạn chỉnh sửa. Di chuyển đi nơi khác và dạng đã render quay lại. Các dòng #set, #show, #import và #let ở đầu tệp được gập lại thành thanh Show document settings, bạn có thể nhấn vào để mở. Bất cứ gì chế độ Visual không vẽ được vẫn hiện trên màn hình dưới dạng mã nguồn. Mọi nút trên thanh công cụ đều viết ra cùng kiểu Typst ở cả hai chế độ, còn số dòng, tìm kiếm, kiểm tra chính tả và lỗi biên dịch vẫn hoạt động.

Dự án mới mở ở chế độ Code, và mỗi dự án ghi nhớ chế độ mà bạn rời đi. Soạn thảo trực quan đề cập việc chuyển này cho cả ba ngôn ngữ.

Trợ giúp trong lúc bạn gõ

Tệp Typst có các trình hỗ trợ giống tệp LaTeX, được viết cho cú pháp Typst:

• Nhấn mũi tên ở gutter để gập một tiêu đề lại, đến tiêu đề cùng cấp tiếp theo. Khối mã, khối nội dung, phương trình và danh sách đối số dài cũng gập được. Xem Gập mã.
• Khi bạn cuộn, các tiêu đề phía trên con trỏ vẫn được ghim ở đầu trình soạn thảo. Một thanh breadcrumb phía trên tệp cho biết bạn đang ở mục nào, và nhấn vào một breadcrumb sẽ nhảy đến tiêu đề đó.
• Gõ $ sẽ thêm dấu $ đóng, và một khoảng trắng bên trong cặp rỗng sẽ biến nó thành công thức hiển thị. Trên một mục danh sách, Enter bắt đầu mục tiếp theo. Trợ giúp gõ Typst liệt kê phần còn lại.
• Language server của Typst gợi ý hoàn thiện hàm, đường dẫn tệp, nhãn, khóa trích dẫn, gói và kiểu tài liệu tham khảo. Xem Gợi ý hoàn thiện Typst.
• Gõ / ở đầu một dòng, hoặc sau một khoảng trắng, để dùng snippet: tiêu đề, hình, bảng, phương trình, chú thích cuối trang, mục lục, tài liệu tham khảo và nhiều thứ khác.
• ⌘/ / Ctrl+/ thêm hoặc bỏ chú thích cho các dòng được chọn bằng //.

Xem trước công thức toán

Khi con trỏ nằm trong một phương trình, Typst vẽ kết quả ngay phía trên nó. Menu của bản xem trước có thể ẩn nó cho đến khi bạn rời phương trình, hoặc tắt hẳn.

Dán công thức LaTeX như $\frac{a}{b}$ vào tệp Typst và nút Paste as Typst math sẽ xuất hiện bên dưới. Nhấn vào nó để thay phần vừa dán bằng công thức Typst, hoặc nhấn Esc để giữ LaTeX. Với công thức LaTeX đã có trong tệp, hãy chọn nó rồi chọn Convert LaTeX math to Typst từ menu chuột phải. Để chuyển đổi đơn lẻ, công cụ Equation to Typst làm điều tương tự bên ngoài dự án.

Thêm hình có chú thích

1. Chọn Insert figure trên thanh công cụ.
2. Chọn plot.png dưới Project images, hoặc chọn Import from disk… để sao chép nó vào dự án.
3. Chọn Three-quarter width, rồi bật Add a caption và Add a label. Nhập chú thích và nhãn fig:measurements.
4. Thêm Alt text mô tả hình ảnh cho trình đọc màn hình, và chọn Placement nếu hình cần trôi lên đầu hoặc cuối trang.
5. Chọn Insert figure.

Oleafly viết một hình như thế này:

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

See @fig:measurements for the comparison.

Để thay đổi hình về sau, đặt con trỏ vào trong hình rồi chọn Insert figure lần nữa. Hộp thoại sẽ mở thành Edit figure với các giá trị hiện tại.

Bảng từ tệp dữ liệu

Nhấn chuột phải trong trình soạn thảo và chọn Table from CSV/XLSX…. Chọn một tệp CSV, TSV, Excel hoặc JSON, xem bản xem trước, rồi thêm chú thích và nhãn nếu muốn. Insert at cursor viết một bảng Typst với các đường kẻ giống bảng của thanh công cụ. Văn bản ô mà Typst sẽ đọc là mã đánh dấu sẽ được escape.

Bật Keep linked to the data file để bảng gắn với dữ liệu của nó. Oleafly sao chép dữ liệu vào thư mục data của dự án, và bảng đọc tệp đó mỗi lần tài liệu biên dịch. Sửa tệp và bảng sẽ thay đổi ở lần biên dịch tiếp theo. Nhập bảng từ tệp dữ liệu mô tả đầy đủ hộp thoại này.

Thêm trích dẫn

Trích dẫn bằng Cite from project, hoặc gõ @ và chọn một khóa từ danh sách gợi ý. Khóa trích dẫn và nhãn tài liệu đều dùng @ trong Typst; tài liệu tham khảo hoặc nhãn cung cấp đích đến.

Đặt tài liệu tham khảo ở nơi bạn muốn danh sách tài liệu xuất hiện:

#bibliography("references.bib")

Tệp có thể là BibTeX (.bib) hoặc Hayagriva (.yml), và lệnh có thể nêu nhiều tệp. Trích dẫn bạn thêm từ References & citations sẽ vào tệp mà tài liệu khai báo, được chuyển sang Hayagriva khi tệp đó cần. Để đổi kiểu tài liệu tham khảo, dùng menu Citation style ở cuối bảng References, menu này viết giúp bạn đối số style:. Xem Chọn kiểu trích dẫn Typst.

Gói, cài đặt và thông tin chi tiết

Ba nút ở đầu bên phải thanh công cụ tác động lên toàn bộ tài liệu:

• Typst packages tìm kiếm trên Typst Universe và viết dòng #import. Khi một lệnh import nêu phiên bản cũ hơn, trình soạn thảo sẽ đề nghị cập nhật. Một dự án cũng có thể giữ riêng bản sao các gói của mình để biên dịch ngoại tuyến. Xem Gói và Gói từ Typst Universe.
• Document insights liệt kê tiêu đề, hình, bảng, phương trình, nhãn, trích dẫn và việc cần làm, đồng thời sao chép tiêu đề, tác giả, từ khóa và tóm tắt cho biểu mẫu nộp bài. Typst đọc tài liệu khi hộp thoại mở, nên các con số và số trang luôn cập nhật. Xem Document insights.
• Document settings thay đổi khổ giấy, lề, số cột, phông chữ phần thân, cỡ chữ, ngôn ngữ, căn lề hai bên, khoảng cách dòng và cách đánh số tiêu đề cùng phương trình. Oleafly ghi lựa chọn của bạn vào quy tắc #set của tệp chính. Nó cũng chứa các biến thể biên dịch của dự án. Xem Document settings.

Lỗi và kiểm tra

Khi biên dịch thất bại, mỗi lỗi được gạch chân trong tệp chứa nó, đúng trên đoạn Typst báo cáo. Di chuột lên vệt gạch chân để đọc thông điệp và gợi ý của Typst. Các lỗi thường gặp, như tên không xác định, thiếu tệp hoặc gói, hoặc dấu ngoặc chưa đóng, đều kèm lời giải thích giản dị. Xem Lỗi biên dịch trong tệp nguồn.

Chính tả và ngữ pháp kiểm tra văn xuôi trong tệp Typst, kể cả chú thích, ô bảng và các trường mẫu như abstract:, đồng thời bỏ qua mã. Preflight kiểm tra tệp nguồn Typst để tìm tham chiếu và trích dẫn chưa xử lý, văn bản thay thế bị thiếu, hình ảnh bị thiếu, siêu dữ liệu tài liệu và các vấn đề về phản biện ẩn danh.

Nhảy giữa tệp nguồn và tệp PDF

Chọn Go to PDF trên thanh công cụ hoặc nhấn ⌘⇧J / Ctrl+Shift+J để nhảy từ con trỏ đến trang. Trong tệp PDF, giữ ⌘ hoặc Ctrl và nhấn vào một từ để nhảy về dòng của nó, kể cả trong tệp được đưa vào bằng #include. Đồng bộ cần Typst 0.13 trở lên. Xem Đồng bộ nguồn và PDF.

Định dạng tệp

Format document làm gọn toàn bộ tệp bằng typstyle. Nhấn ⇧⌥F / Shift+Alt+F hoặc chọn nó từ menu chuột phải. Format selection chỉ định dạng các dòng được chọn. Để định dạng mỗi lần bạn nhấn ⌘S / Ctrl+S, bật Format on save dưới mục Typst trong Settings → Appearance → Editor. Xem Định dạng tệp Typst.

Các phiên bản Typst

Oleafly đi kèm Typst 0.15.1, và Settings → Engines → Typst liệt kê Typst 0.11 đến 0.15 để tải xuống. Dự án mới sẽ ghim phiên bản mặc định, nhờ vậy cách ngắt dòng và số trang giữ nguyên khi sau này Oleafly phát hành 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à chọn dưới Typst version (this project). Language server bám theo phiên bản của dự án. Các phiên bản Typst giải thích việc ghim phiên bản, các phiên bản còn thiếu và cách thử một bản phát hành mới trước khi bạn chuyển sang.

Tổ chức và xuất tệp

Chia một báo cáo dài thành nhiều tệp và đưa chúng vào bằng #include "sections/method.typ". Giữ các hình, dữ liệu, phông chữ và tệp tài liệu tham khảo trong dự án để tệp ZIP nguồn mang theo mọi thứ tài liệu cần.

Biên dịch để kiểm tra kết quả, rồi mở Export. Nó cung cấp Export as PDF, Export source (.zip), Export page as PNG và Images and HTML, vốn ghi các trang PNG hoặc SVG hoặc một tệp HTML bằng chính Typst. Trên Typst 0.13 trở lên, việc xuất Word, HTML, Markdown, LaTeX và văn bản thuần đi qua đầu ra HTML của riêng Typst, nên phương trình và tham chiếu được giữ nguyên. Xem Xuất và chuyển đổi dự án. Biên dịch giải thích nhật ký và tùy chọn biên dịch, còn tệp và thư mục đề cập việc tổ chức dự án.

Để chuyển một dự án LaTeX sẵn có sang Typst, xem Chuyển dự án LaTeX sang Typst.