Sunday 27 February 2022

Tạo website với Jupyter Notebook & GitHub Pages

Fact: Nếu bạn đã biết đến nbviewer.com thì chắc bạn không cần đọc tiếp! Bài này cũng thích hợp với các bạn muốn build 1 blog chia sẻ về toán, muốn viết lách ít và chủ yếu nhúng công thức $\LaTeX$ là nhiều.

Kết thúc bạn sẽ có 1 site tương tự thế này: https://trhgquan.github.io/crypto

Repository của site trên GitHub: https://github.com/trhgquan/crypto.


---

FAQ

Q: Vì sao lại là Jupyter Notebook?

A: Vì Jupyter Notebook có hỗ trợ Markdown $\LaTeX$. Jupyter Notebook cũng có chức năng export ra Markdown (và mình sẽ dùng tính năng này - convert file Notebook ra Markdown, rồi upload lên GitHub Pages).

Q: Rồi có cần cài thêm gì không?

A: Thực ra là enable GitHub Pages cho GitHub repository là đủ. Tuy nhiên nếu như bạn xài $\LaTeX$ (như mình :D ) sẽ phải config lại tí xíu để render ra đúng công thức.

Dô!

1. Jupyter Notebook

Để export Notebook ra Markdown, bạn vào File > Download as > Markdown (.md). 


Bấm vào là có file Markdown download về ngay. Nếu trong notebook của bạn có ảnh (matplot generate ra chẳng hạn) thì sẽ download về một file .zip, trong đó là file Markdown và các ảnh trong notebook.

Tips: bạn cũng có thể chọn download as html như hình. Ở đây mình xài Markdown vì mình quen xài Markdown hơn :/

2. Repository & GitHub Pages

Vào Settings > Pages. Bạn chọn branch mà website lấy để dựng site, rồi chọn folder (mặc định là ở root /). Save lại là xong rồi á!

Giờ bạn push mấy cái file vừa rồi lên repository này, chờ cho workflow chạy xong là ngon lành. Jekyll sẽ render mấy file Markdown của bạn ra thành html, xong convert thành site cho bạn.

Ê nhưng mà..

3. Render $\LaTeX$

a. Naive

Như đã nói bên trên, Markdown mặc định không hỗ trợ $\LaTeX$. Bạn phải thêm-cái-gì-đó thì mới render được. Thường thì mấy site (và kể cả blog của mình lmao) sẽ dùng MathJax (https://mathjax.org). Xài MathJax tiện lợi ở chỗ nhúng $\LaTeX$ vào thì nhanh.

Nếu bạn search trên Google thì sẽ thấy hướng dẫn thế này: "Tạo file _includes/head.html, rồi chèn MathJax script tag vào ..etc". Nhưng chú ý là bạn không tạo "head.html", mà là "head-custom.html".

Nội dung file như sau: https://github.com/trhgquan/crypto/blob/main/_includes/head-custom.html.

Xong thì sao nữa? Push code lên GitHub thôi.

b. Ê nhưng mà, code em vẫn không render đúng anh ơi :(

Mình sẽ miêu tả problem của bạn thế này: code $\LaTeX$ của bạn ở local thì render rất đẹp, lên site thì bể tùm lum. Giả sử bạn có đoạn (Z^{*}_7, \cdot_{7}), đáng lẽ render thành $(Z^{*}_7, \cdot_{7})$ thì nó render thành (Z^{*}7, \cdot{7}).

Vì sao lại vậy? Nên nhớ là Markdown sẽ được render lại bằng Jekyll, sau đó mới qua MathJax render thành công thức toán; mà Jekyll render code Markdown rất ngu! Nó sẽ nhận xét 2 dấu gạch dưới (_) đánh dấu đoạn cần in nghiêng, và nó in nghiêng (bằng cách chèn thẻ <em> vào giữa) đoạn-đáng-lẽ-nên-giữ-nguyên!

Vậy làm sao để né? Bạn làm cho mình một thao tác, là đặt đoạn code render bị lỗi vào giữa thẻ <div> hoặc thẻ <span>. Như vậy sẽ bảo Jekyll "à tiên sư thằng này, trong này cấm mày động vào". Và thế là code sẽ không bể nữa.

Với lựa chọn download ra html từ file Notebook thì bạn sẽ không lo code bị bể (omg).

c. Ê nhưng mà, tại sao em lại ăn 404 :(

File Markdown của bạn tên gì thì gõ cái tên đấy vào navbar. Ví dụ mình đặt tên file Markdown là meow.md, thì vào https://tentao.github.io/repo/meow

Ê nhưng mà đâu thằng nào rảnh? Mặc định GitHub nó sẽ chọn README.md hoặc index.md là trang index. Nếu bạn vẫn không hiểu thì rename cái file Markdown sang index sẽ fix lỗi 404 á!

Chốt

Qua bài post này:

  • Bạn sẽ học được cách tạo GitHub Page với Jupyter Notebook. Nhớ là để repo public, để private mà muốn có site thì phải nâng cấp lên Pro.
  • Bạn sẽ học được cách tạo file Markdown từ Jupyter Notebook.

Tuy nhiên nhớ tự chỉnh sửa thêm mắm muối gì gì đấy để nó đúng ý bạn nhé :D Mình làm kiểu mì ăn liền nên nó chạy là được.

Happy coding!

No comments:

Post a Comment

Popular posts