Quarto là hệ thống soạn thảo khoa học mã nguồn mở: bạn viết văn bản và mã R hoặc Python trong một tệp .qmd, Quarto chạy mã, chèn bảng, hình, số liệu vào đúng chỗ rồi xuất ra Word, PDF, HTML, slide. Đổi dữ liệu thì chạy lại một lệnh, mọi con số trong bài cập nhật theo.
Cách làm phổ biến là phân tích trong R hoặc SPSS, chép bảng sang Word, chụp hình dán vào. Mỗi lần dữ liệu đổi, phải chép lại từ đầu và rất dễ sót một con số trong phần thảo luận. Quarto, kế thừa R Markdown và do Posit phát triển, gom phân tích và văn bản về một nguồn. Bài này hướng dẫn những gì cần cho một bài báo thật, kể cả phần mà tạp chí đòi hỏi: tệp Word đúng mẫu và danh mục tài liệu tham khảo đúng kiểu.
Cấu trúc một tệp .qmd
Phần đầu YAML
Đầu tệp là khối giữa hai dòng ---, khai báo thông tin và đầu ra. Ví dụ các dòng: title: Thu nhập và tiếp cận tín dụng của hộ nông thôn, author: Nguyễn Thị An, bibliography: tailieu.bib, csl: apa.csl, và khối format: liệt kê các đầu ra như html: default, docx: kèm dòng thụt vào reference-doc: mau-tap-chi.docx.
Văn bản Markdown
Phần thân viết bằng Markdown: dấu # cho đề mục, dấu sao cho chữ nghiêng và đậm, gạch đầu dòng cho danh sách. Người quen Word chỉ mất một buổi để quen. RStudio và Positron có chế độ soạn trực quan hiển thị gần giống Word, bật bằng nút chuyển giữa nguồn và trực quan.
Khối mã
Mã đặt trong khối bắt đầu bằng ba dấu backtick kèm tên ngôn ngữ trong ngoặc nhọn, ví dụ {r} hoặc {python}. Tuỳ chọn của khối ghi ở đầu khối với tiền tố #|: #| echo: false để ẩn mã khỏi bài báo, #| label: fig-thunhap và #| fig-cap: Phân bố thu nhập theo vùng để đặt nhãn và chú thích hình.
Chạy mã R và Python bên trong
Khi tệp chỉ có khối R, Quarto dùng knitr để chạy. Khi chỉ có khối Python, Quarto dùng Jupyter, máy cần cài Python với gói jupyter. Muốn trộn R và Python trong cùng một tệp, chạy bằng knitr và dùng gói reticulate để R gọi Python; cách này chạy được nhưng thêm một tầng phụ thuộc, nên chỉ dùng khi thật cần.
Số liệu nằm trong câu văn cũng tính từ mã được, gọi là mã trong dòng. Với R, viết `r round(hs_thunhap, 2)` giữa câu; với Python cũng có cú pháp tương ứng. Nhờ đó câu “hệ số thu nhập là 0,27” tự cập nhật khi mô hình đổi. Lưu ý định dạng số: R mặc định in dấu chấm thập phân, muốn dấu phẩy theo kiểu Việt thì định dạng bằng hàm như format(x, decimal.mark = ',').
Với phân tích chạy lâu, bật tuỳ chọn freeze hoặc cache để Quarto không chạy lại mọi khối mỗi lần xuất, chỉ chạy khi mã thay đổi.
Cài đặt ban đầu gồm hai phần: bản Quarto tải từ trang chính thức cho hệ điều hành của bạn, và ngôn ngữ bạn dùng. RStudio các bản gần đây đã kèm sẵn Quarto. Kiểm tra cài đặt bằng lệnh quarto check, lệnh này báo Quarto tìm thấy R, Python, Jupyter, LaTeX hay chưa, rất tiện khi gặp lỗi không rõ nguyên nhân lúc xuất bài.
Trích dẫn và tham chiếu chéo
Trích dẫn từ tệp .bib
Xuất thư viện Zotero ra tệp BibTeX, hoặc dùng tiện ích Better BibTeX để tệp tự cập nhật. Trong văn bản viết [@nguyen2021] cho trích dẫn trong ngoặc, @nguyen2021 cho trích dẫn trong câu, [@nguyen2021; @tran2023, tr. 15] cho nhiều nguồn. Kiểu trình bày do tệp CSL quyết định; kho Citation Style Language có sẵn hàng nghìn kiểu của các tạp chí. Danh mục tài liệu tham khảo tự sinh ở cuối bài.
Tham chiếu chéo hình và bảng
Hình có nhãn bắt đầu bằng fig-, bảng bắt đầu bằng tbl-. Trong văn bản viết @fig-thunhap, Quarto tự đánh số và chèn “Hình 1”. Đổi thứ tự hình, số tự đổi theo. Tiền tố mặc định theo ngôn ngữ khai ở dòng lang; muốn chắc chữ hiện đúng tiếng Việt, tự khai trong YAML ở khối crossref: các dòng fig-title: Hình và tbl-title: Bảng.
Xuất Word theo mẫu tạp chí
Đây là đầu ra hay dùng nhất vì đa số tạp chí trong nước nhận tệp Word.
- Tạo tệp mẫu: chạy
quarto pandoc -o mau-tap-chi.docx --print-default-data-file reference.docxđể lấy mẫu mặc định. - Mở tệp mẫu bằng Word, sửa các kiểu (style) như
Normal,Heading 1,Title, chú thích, theo yêu cầu phông, cỡ chữ, giãn dòng của tạp chí. Chỉ sửa kiểu, nội dung trong tệp mẫu không quan trọng. - Khai trong YAML: dưới
docx:thêmreference-doc: mau-tap-chi.docx. - Xuất bằng
quarto render bai-bao.qmd --to docx. - Mở tệp kết quả, kiểm bảng, hình, tài liệu tham khảo. Những chỉnh sửa nhỏ cuối cùng làm trực tiếp trong Word, nhưng ghi lại để lần sau đưa vào mẫu.
Với tạp chí quốc tế dùng LaTeX, có các mẫu dựng sẵn trong bộ quarto-journals, cài bằng lệnh quarto use template kèm tên mẫu, ví dụ mẫu của Elsevier hay PLOS.
Một nguồn, nhiều đầu ra
Cùng một nội dung phân tích có thể sinh các sản phẩm khác nhau bằng cách đổi khối format:
| Đầu ra | Khai báo | Dùng khi |
|---|---|---|
| Word | docx | Nộp tạp chí trong nước, gửi đồng tác giả sửa bằng theo dõi thay đổi |
pdf, cần cài TinyTeX bằng quarto install tinytex | Bản thảo tiền ấn phẩm, báo cáo nghiệm thu | |
| Trang web | html | Phụ lục trực tuyến, báo cáo nội bộ có hình tương tác |
| Slide | revealjs hoặc pptx | Trình bày hội thảo, bảo vệ luận án |
| Website nhiều trang | Dự án có tệp _quarto.yml với kiểu dự án website | Trang của phòng thí nghiệm, sổ tay phương pháp |
Slide thường viết trong tệp .qmd riêng nhưng gọi lại cùng mã và cùng dữ liệu, ví dụ đọc kết quả đã lưu từ bước phân tích. Như vậy hình trên slide và hình trong bài luôn khớp nhau.
Tổ chức dự án Quarto cho một bài báo
Thư mục gọn
Đặt tệp bai-bao.qmd ở gốc dự án, cạnh tệp tailieu.bib, tệp CSL và tệp mẫu Word. Mã phân tích nặng nên tách ra thư mục ma/ và lưu kết quả trung gian như mô hình đã ước lượng, bảng tổng hợp; tệp .qmd chỉ đọc kết quả đó để trình bày. Như vậy xuất bài chỉ mất vài giây và lỗi trong bước phân tích không làm hỏng việc xuất bản thảo.
Tệp cấu hình dự án
Khi có nhiều tệp như bài báo, phụ lục, slide, tạo tệp _quarto.yml ở gốc để khai các tuỳ chọn chung như tài liệu tham khảo, ngôn ngữ, kiểu trích dẫn. Lệnh quarto render không kèm tên tệp sẽ xuất cả dự án.
Xem trước khi viết
Lệnh quarto preview bai-bao.qmd mở bản xem trước trong trình duyệt và tự làm mới mỗi khi lưu tệp, tiện khi chỉnh văn bản và hình cùng lúc.
Theo dõi bằng Git
Tệp .qmd là văn bản thuần nên Git hiển thị từng dòng thay đổi, khác hẳn tệp Word. Đưa tệp nguồn, tệp .bib, tệp mẫu vào Git; tệp xuất ra và thư mục tạm như _freeze tuỳ nhóm quyết định có theo dõi hay không.
Khi nào không nên dùng Quarto?
Đồng tác giả chỉ làm việc bằng Word và theo dõi thay đổi. Sửa của họ nằm trong tệp Word, phải chép tay ngược về .qmd. Với bài có nhiều người sửa văn, cách thực tế là dùng Quarto cho phần phân tích, xuất bảng và hình, còn viết văn trong Word.
Bài thuần lý thuyết, không có phân tích số liệu. Lợi ích lớn nhất của Quarto là gắn mã với văn bản; không có mã thì lợi ích còn rất ít.
Hạn nộp gấp mà chưa từng dùng. Học Quarto trong tuần nộp bài là tự làm khó mình. Bắt đầu bằng báo cáo nội bộ hay phụ lục trước.
Tạp chí yêu cầu định dạng rất đặc thù. Mẫu Word có thể không mô phỏng được mọi chi tiết, như đánh số dòng hay bảng xoay ngang. Thử xuất sớm để biết phải chỉnh tay bao nhiêu.
Câu hỏi thường gặp
Quarto khác R Markdown thế nào?
Quarto là thế hệ kế tiếp của R Markdown, cũng do Posit phát triển, nhưng là công cụ độc lập, hỗ trợ cả Python, Julia và chạy ngoài RStudio. Phần lớn tệp R Markdown chạy được trong Quarto với ít chỉnh sửa.
Có cần cài LaTeX để dùng Quarto không?
Chỉ cần khi xuất PDF. Lệnh quarto install tinytex cài một bản LaTeX gọn. Xuất Word, HTML hay slide revealjs thì không cần LaTeX.
Quarto có dùng được với Zotero không?
Được. Có thể xuất thư viện Zotero thành tệp .bib, hoặc chèn trích dẫn trực tiếp từ Zotero trong chế độ soạn trực quan của RStudio. Kiểu trình bày chọn bằng tệp CSL.
Dùng Quarto trong VS Code được không?
Được. Quarto có tiện ích mở rộng cho VS Code và Positron, hỗ trợ xem trước, chạy khối mã và chế độ soạn trực quan. Cũng có thể dùng lệnh quarto trong Terminal với bất kỳ trình soạn thảo nào.
Tệp Word xuất ra có giữ được theo dõi thay đổi không?
Tệp xuất ra là tệp Word bình thường, đồng tác giả bật theo dõi thay đổi được. Nhưng mỗi lần xuất lại từ .qmd sẽ tạo tệp mới, các sửa đổi trong Word không tự quay về tệp nguồn.
