Monday 19 February 2024

Compile project $\LaTeX$ với GitHub Actions

 Không cần lên Overleaf, không cần cài $\TeX$ hay TeXStudio cũng compile được file .tex ra .pdf

Đặt vấn đề

Bạn có một project $\LaTeX$ đang lưu trữ mã nguồn trên GitHub và muốn compile ra pdf sau mỗi commit. Khi đó mình chỉ cần cài đặt một workflow gồm:

Ví dụ

Mình đang build CV sử dụng template A Customised CurVe CV, cấu trúc thư mục (và repository) CV của mình như sau:


Trong thư mục a-customised-curve-cv, file cv-llt.tex là file chính để compile ra pdf. Lưu ý là bạn cần phải xác định chính xác file .tex để compile. Khi đó ta setup một workflow (compile-and-release.yml) như sau:


Trong đó:

  • Dòng 3 tới dòng 6 thể hiện workflow sẽ chạy nếu có commit push tới một tag. Mình sẽ lưu ý rõ mục này ở các phần sau.
  • Dòng 12 và 13 định nghĩa action checkout - tất cả các workflow cần checkout vào repository để có thể hoạt động trên repository đó.
  • Dòng 15 tới dòng 19 là phần quan trọng nhất của workflow - compile file .tex ra .pdf. Ở đây mình "giấu" path của working directory (dòng 18) và root file (dòng 19) vào các biến action variable (cách "giấu", xem tại đây). Bạn có thể hiểu working directory là folder lưu file .tex cần compile và root file là file .tex cần compile (đã nêu bên trên).
  • Dòng 21 tới dòng 30 là định nghĩa action create release. Ở đây action đòi hỏi GitHub Token, sử dụng github.ref  - hành động trigger workflow, ở đây là tên tag. Ở đây mình set prerelease và draft là false, bạn có thể set true tùy ý, (các release draft sẽ không hiện công khai, các prerelease sẽ có badge ghi chú bản prerelease).
  • Dòng 32 tới dòng 41 là định nghĩa action upload file pdf đã compile lên release vừa tạo. Ở đây upload_url sử dụng lại địa chỉ release đã tạo ở action trước, bạn copy nguyên xi vào. asset_path là vị trí file pdf, thường là working_dir/<tên file tex>.pdf. asset_name tương tự, asset_content_type để là pdf.

Setup xong action thì save lại và .. test thôi

Test 

Lưu ý là workflow được config để trigger khi bạn push lên tag (đọc thêm về tagging trong Git ở đây). Ta commit, sau đó tag version cho bản update:


Sau đó push lên GitHub và đợi workflow chạy xong, bạn sẽ thấy mục Release có thêm 1 release mới:


File pdf sẽ nằm trong mục Asset. Nếu bạn muốn chỉnh cho workflow chạy sau mỗi commit, chỉnh file workflow thành như sau:


Nhớ thay branch main thành branch tùy ý bạn muốn build.

Tổng kết

Vậy là mình đã giới thiệu một cách build file $\LaTeX$ thành pdf mà không cần Overleaf hay tải TeXStudio. Phần còn lại các bạn nên tự nghịch để biến tấu workflow sao cho phù hợp với nhu cầu của mình, đi chi tiết lại quá .. dài dòng mà lại còn mất thời gian.

Happy coding!

No comments:

Post a Comment

Popular posts