Dễ dàng tạo file readme với Readme.so

Readme là một file hướng dẫn hầu như bắt buộc phải có để người sử dụng có được cái nhìn khách quan về source code như mục đích sử dụng, cách xây dựng và vận hành. Hiện nay, các file readme đều được viết bằng ngôn ngữ Markdown do sự bắt mắt trong cách trình bày nội dung và rất nhiều các nền tảng nổi tiếng đều hỗ trợ định dạng ngôn ngữ này như Github, Reddit hay Stack Exchange.

Tuy vậy, để xây dựng file readme với định dạng Markdown thì chúng ta phải nắm được các cú pháp để trình bày, một thứ khá là khó để nhớ hết được. Điều này khiến anh bạn Nekogami phải hì hục hồi lâu mỗi khi phải viết file readme cho dự án để thành viên mới có thể sử dụng.

Để anh bạn mình bớt đau khổ, đã tới lúc cần tới bảo bối hỗ trợ viết file readme - một công cụ đơn giản mà hiệu quả đó là Readme.so. Đây là công cụ giúp rút ngắn thời gian viết và trình bày file readme cho dự án mà chúng ta sẽ cùng tìm hiểu trong bài viết này.

Giới thiệu về Readme.so

Readme.so là một công cụ hỗ trợ chúng ta chỉnh sửa và trình bày file readme. Giao diện của hệ thống khá đơn giản và dễ hiểu, bạn có thể bắt đầu viết file mà không cần phải mày mò quá lâu để nắm được cách sử dụng. Nếu không muốn sử dụng trực tiếp trên trang chủ của hệ thống của trang web thì bạn cũng có thể kéo source code về để chạy offline trên máy của mình.

Triết lý của readme.so là chia file readme thành nhiều phần (section). Mỗi phần là một template được trình bày sẵn để chúng ta có thể chỉnh sửa nội dung bên trong mà không ảnh hưởng đến cấu trúc của file.

Việc chúng ta cần làm là chọn những phần cần dùng sắp xếp theo ý muốn trong phần “Sections” nằm bên trái giao diện. Các nút để thao tác thêm, xóa, reset hay thay đổi thứ tự từng phần rất dễ nhận biết và đơn giản, các bạn có thể dễ dàng nhận ra trong hình bên dưới. Nếu không có template phù hợp, bạn cũng có thể tự tạo mẫu riêng và thêm vào trong file readme của mình thông qua nút “Custom Section” ở phần chọn section.

Nội dung của mỗi phần được chỉnh sửa trong khung “Editor”, chú ý đừng xóa nhầm các từ khoá của file để không làm hỏng giao diện nhé. Bạn cũng có thể sửa hẳn template trong phần editor cho đẹp mắt mình hơn hoặc copy nội dung và chỉnh sửa trong “Custom template”.

Bên phải ngoài cùng là khung “Preview” để hiển thị phần giao diện thực tế của file readme để chúng ta có thể xem nội dung sau khi chỉnh sửa. Ta cũng có thể chuyển qua tab "Raw" để xem file gốc và copy về máy.

Readme.so cũng có chế độ dark mode và hỗ trợ download file readme về máy.

Khả năng mở rộng

Nếu cảm thấy nội dung của các template có sẵn không phù hợp với mục đích sử dụng của mình, chúng ta có thể trực tiếp fork source code của Readme.so và tiến hành tạo và chỉnh sửa template cho phù hợp với dự án hiện có. Nội dung của các template đều được chứa trong các file json trong thư mục “data”.

Cấu trúc file khá đơn giản để chúng ta có thể thao tác trên đó. Sau đây là một ví dụ đơn giản để hỗ trợ tạo bài viết trong Atekco (đúng vậy, các bài viết của Atekco đều được lưu dưới định dạng Markdown.

Tiềm năng mở rộng thêm của hệ thống là khá lớn khi ta có thể chỉnh sửa thêm giao diện cho phù hợp, đưa phần template xuống database để dễ thay đổi hay thậm chí dùng để xây dựng các file viết bằng ngôn ngữ khác thay vì chỉ cho Markdown.

Kết luận

Sau những trải nghiệm với Readme.so, một trang công cụ đơn giản nhưng khá hiệu quả để tạo ra các file readme cho dự án. Các bạn có thể ủng hộ tác giả của thư viện trên để có thể có thêm các tính năng hay ho hơn nhé.