ProperDocs: Bản kế thừa MkDocs ra đời để thay thế công cụ tạo tài liệu bị bỏ rơi

ProperDocs: Bản kế thừa MkDocs ra đời để thay thế công cụ tạo tài liệu bị bỏ rơi

MkDocs, công cụ tạo trang tĩnh (static site generator) phổ biến dùng để viết tài liệu kỹ thuật, đang đối mặt với một cuộc khủng hoảng quản lý nghiêm trọng. Để giải quyết tình trạng này, một nhóm các nhà phát triển cũ đã ra mắt ProperDocs — một bản kế thừa được thiết kế để thay thế trực tiếp MkDocs, đảm bảo sự ổn định cho cộng đồng người dùng.

Bối cảnh: MkDocs bị bỏ rơi

Theo oprypin, người bảo trì (maintainer) cuối cùng của MkDocs, dự án này hiện tại hoàn toàn không được duy trì. Tác giả gốc đã nắm quyền kiểm soát trong 2 năm qua nhưng phớt lờ mọi phản hồi, vấn đề kỹ thuật và đề nghị chuyển giao dự án. Điều đáng lo ngại hơn là kế hoạch cho "MkDocs 2.0".

Tác giả gốc có ý định sử dụng lại tên gọi MkDocs cho một trình tạo tài liệu hoàn toàn mới. Điều này sẽ dẫn đến việc phá vỡ hoàn toàn khả năng tương thích với tất cả các theme và plugin hiện có. Người dùng sẽ không có phương án thay thế nào và cấu hình hiện tại của họ có thể trở nên vô dụng. Việc chạy lệnh pip install mkdocs trong tương lai sẽ trở thành một canh bạc rủi ro đối với hệ thống tài liệu của bất kỳ doanh nghiệp hay cá nhân nào.

Giải pháp: ProperDocs

Để đối phó với rủi ro này, cộng đồng đã phát triển ProperDocs. Đây là một bản fork (nhánh phát triển) được chăm chút kỹ lưỡng từ mã nguồn của MkDocs.

"Chúng tôi chào đón mọi người đến với sự kế thừa của chúng tôi từ nơi MkDocs đã dừng lại, đặt tên là ProperDocs. Bạn đã có thể cài đặt và sử dụng nó như một giải pháp thay thế trực tiếp cho MkDocs."

Hiện tại, ProperDocs hoạt động giống hệt MkDocs nhưng đã bao gồm các bản sửa lỗi quan trọng nhất. Trong tương lai, dự án hứa hẹn sẽ tiếp tục phát triển các tính năng mới mà MkDocs gốc đã bỏ lỡ.

Hướng dẫn chuyển đổi cho người dùng

Việc chuyển đổi từ MkDocs sang ProperDocs cực kỳ đơn giản và không đòi hỏi thay đổi cấu hình phức tạp.

1. Thay thế dependency

Nếu bạn đang sử dụng MkDocs, hãy thay thế gói cài đặt ngay lập tức:

Trước đây: pip install mkdocs mkdocs-foo-plugin

Bây giờ: pip install properdocs mkdocs-foo-plugin

Lưu ý rằng các plugin vẫn giữ nguyên tên và hoạt động bình thường, các nhà phát triển plugin không cần phải đổi tên dự án của họ.

2. Thay đổi lệnh build

Thay đổi tên lệnh trong quy trình xây dựng (build) hoặc deploy của bạn:

Trước đây: mkdocs build

Bây giờ: properdocs build

Tất cả các tham số dòng lệnh khác đều giữ nguyên.

3. Các bước tùy chọn khác

• Bạn có thể đổi tên file cấu hình từ mkdocs.yml sang properdocs.yml (nhưng không bắt buộc).
• Nếu bạn sử dụng các theme mặc định như "mkdocs" hoặc "readthedocs", bạn cần cài đặt chúng thủ công vì ProperDocs đã loại bỏ chúng khỏi cài đặt mặc định để giúp gói phần mềm nhẹ hơn. Đây là thay đổi duy nhất có thể coi là breaking change.

Gọi gọi các nhà phát triển Plugin

ProperDocs đang kêu gọi sự hỗ trợ từ các tác giả plugin để lan tỏa cảnh báo này đến người dùng cuối. Các plugin không cần phải từ bỏ người dùng MkDocs, nhưng nên thêm ProperDocs vào danh sách phụ thuộc và giới hạn phiên bản MkDocs (ví dụ: mkdocs >=1.2.3, <=1.6.1) để ngăn chặn các bản cập nhật trong tương lai gây lỗi hệ thống.

Nhiều dự án phụ thuộc lớn đã bắt đầu chuyển hướng. Ví dụ, MaterialX — bản kế thừa của theme Material for MkDocs nổi tiếng — đã tuyên bố ủng hộ ProperDocs và sẽ cập nhật tài liệu để hướng dẫn người dùng chuyển đổi.

Với sự xuất hiện của ProperDocs, cộng đồng người dùng MkDocs giờ đây có một "bến đỗ" an toàn để tiếp tục phát triển hệ thống tài liệu mà không lo ngại về việc bị phá vỡ bởi những quyết định đơn phương từ dự án gốc.