Mkdocs

MkDocs – Phần mềm dựng site document cực tốt

Hi các bạn,

Trong công việc, việc document lại code, document lại các libraries trong dự án, business logics,… là điều dường như tất yếu phải không. Có thể chúng ta có rất nhiều cách để thỏa mãn vụ này như viết Word, Google Docs, GitLab wiki,…

Tuy nhiên những cách thông thường như vậy, ta quản lý document của ta rất khó, rất nhiều và lung tung. Và đôi khi, ta cần search 1 chi tiết nào đó, ta sẽ ko search dc mà phải chui vào từng files, từng trang,… Một cực hình phải ko.

Và từ đó, ta sẽ tìm ra 1 hướng khác, làm ra 1 site để chứa document và hỗ trợ ta tìm kiếm document cần thiết, nhưng mà nếu code thì khá tốn thời gian, cũng như các libraries free ngoài kia, họ ko hề code 1 site document mà họ dùng một phần mềm nhất định để hỗ trợ họ viết và dựng ra site document theo ý họ muốn.

Mình đã sử dụng và hôm nay sẽ giới thiệu với bạn luôn phần mềm có tên là: MkDocs.

1/ Giới thiệu về MkDocs

MkDocs là một phần mềm cực nhanh, dễ sử dụng hỗ trợ bạn generate ra site document theo ý của bạn.

Các dạng files document MkDocs hỗ trợ:

  • Markdown (phổ biến nhất)
  • Text (txt)
  • Html

MkDocs sẽ dựng ra các trang html và bạn có thể host site document mọi nơi (Apache, Nginx, IIS,…) và ngay cả GitHub pages.

Trang chủ: https://www.mkdocs.org/

2/ Yêu cầu tối thiểu

Đã cài Python (https://www.python.org/downloads/)

Các version Python mà MkDocs hỗ trợ: 2.7, 3.4, 3.5, 3.6, 3.7

Lưu ý đối với các bạn xài WINDOWS, khi cài xong nhớ tick dòng này trước khi tắt nhé:

Add Python to PATH

Sau khi cài xong, bạn có thể bật Command Line (cmd) lên để check python và pip với lệnh như sau:

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2

3/ Cài đặt MkDocs

Chỉ đơn giản là chạy lệnh này 😀

pip install mkdocs

Sau khi cài xong, bạn có thể kiểm tra version như sau:

$ mkdocs --version
mkdocs, version 0.15.3

4/ Tạo ra project document đầu tiên

Thông qua 1 dòng lệnh này, bạn sẽ tạo ra được một project document:

 

Project sẽ có cấu trúc như sau:

The initial MkDocs layout

Trong đó:

  • mkdocs.yml là file config chính về trang document của bạn (config title, sidebar,…)
  • docs là thư mục bạn sẽ chứa toàn bộ document trong đó.

5/ Dựng dev-server để test trang document

Với lệnh:

mkdocs serve

Bạn sẽ dựng ra được 1 dev-server và bạn có thể vào url mà MkDocs cung cấp để test document của mình 😀

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

Ngoài ra, nếu bạn muốn dev-server chạy và xem dc trong toàn bộ mạng LAN local, các bạn có thể xài lệnh này:

mkdocs serve -a 0.0.0.0:8080

Như thế thì site dev này với những người trong mạng LAN sẽ truy cập và xem được.

Site khi ta chạy dev và vào thử khi vừa mới tạo project:

The MkDocs live server

6/ Build ra trang document

Chạy lệnh sau để build ra trang document:

mkdocs build

Sau khi build xong, các bạn sẽ thấy thư mục có tên site trong root project folder của bạn. Bạn có thể copy thư mục đó và deploy lên server mà bạn muốn, rất là light-weight phải ko nhỉ? 😀

7/ Cách viết document, cấu hình trang document, themes,…

Cách viết document: sử dụng markdown syntax là chính, bạn có thể mix giữa html và markdown nếu muốn, Mkdocs vẫn hiểu 😀

Thông tin thêm:  https://www.mkdocs.org/user-guide/writing-your-docs/

Về cách cấu hình trang document (tiêu đề, theme, sidebar,…), các bạn có thể tham khảo tại: https://www.mkdocs.org/user-guide/configuration/

8/ Kết luận

Với MkDocs, các bạn có thể dựng ra trang document theo ý muốn, nhỏ gọn, dựng nó theo ý bạn và hỗ trợ người sử dụng trang document bạn tiếp cận nhanh, gọn dễ hơn cũng như là khả năng tìm kiếm document.

Lưu ý là ta nên sử dụng Markdown nhé, để nó có thể dựng ra Table of Contents cho page của bạn được cũng như phát huy khả năng tìm kiếm của tốt nhất nó 😀

Cám ơn các bạn đã quan tâm theo dõi!

From Seth Phat (Documentation Specialist)  with love!

facebook
Seth Phát

Seth Phát

Mình là Phát - biệt danh Seth Phát. Hiện đang là một Sr. Full-Stack Engineer. Mình là một người yêu thích và đam mê lập trình và hiện tại đang theo về phần Web là chủ yếu. Mạnh Back-end và khá Front-end, vẫn đang theo đều cả 2 :v. Còn gì bằng khi được làm những thứ mà mình yêu thích, đam mê ;)

Leave a Reply

Your email address will not be published. Required fields are marked *

Bình luận qua Facebook