Tạo tài liệu với các tập tin Markdown Sử dụng Docsify

Để tạo một trang Web không phải là điều dễ dàng, cần phải tập trung nhiều nguồn lực cho việc này. Một plugin miễn phí sẽ cung cấp cho chúng ta khả năng tạo một trang thực sự thật tuyệt vời...

Nếu bạn đang tạo một plugin miễn phí, khuôn khổ hoặc mã nguồn mở, bạn sẽ cần tài liệu. Điều quan trọng là phải ghi lại công việc của bạn, cho cả tinh thần của bạn và để giúp đỡ những người khác muốn học nguồn lực tuyệt vời của bạn.

Tuy nhiên, tạo ra tài liệu trực tuyến có thể là một nỗi đau thực sự. Rất may, Docsify làm cho nó dễ dàng hơn bằng cách cung cấp một máy phát tài liệu miễn phí chạy trên Markdown.

Đây không phải là máy tạo trang tĩnh điển hình và nó không yêu cầu các trang HTML / CSS tĩnh. Thay vào đó, nó tải tệp Markdown một cách năng động và hiển thị chúng dưới dạng các trang web. Khá gọn gàng!

Kiểm tra trang chủ Docsify để xem bản bố cục, cùng với chi tiết thiết lập thêm.

Nó yêu cầu bạn tự tạo ra tệp index.html, sau đó có thể tải lên GitHub Pages hoặc lưu trữ trên máy chủ của chính bạn. Từ đó, bạn chỉ cần viết tệp Markdown cho mỗi trang và sử dụng các tệp đó làm tài liệu chính của bạn.

Toàn bộ quá trình được vạch ra một cách chi tiết trong hướng dẫn bắt đầu nhanh, vì vậy đó có lẽ là nơi tốt nhất để bắt đầu. Điều này tất cả có thể chạy qua NPM, do đó, nó thực sự giúp để biết nhắc lệnh của bạn hoặc ít nhất là sẵn sàng để tìm hiểu.

Bạn có thể tự tạo một tệp HTML thô và chỉ cần sao chép / dán mẫu từ hướng dẫn thiết lập của Docsify. Nhưng, tôi khuyên bạn nên làm nó một cách năng động, vì nó tiết kiệm được một khoảng thời gian - và đó không phải là vấn đề thực sự?

Khi bạn học hệ thống Docsify, bạn có thể thêm các tính năng sử dụng Markdown hoặc HTML thô. Các tính năng này bao gồm một thanh điều hướng tùy chỉnh và thậm chí trang bìa của riêng bạn với biểu trưng của dự án.

Docsify thậm chí được đóng gói với một loạt các chủ đề miễn phí nếu bạn muốn bố cục được thiết kế sẵn để làm việc. Hoặc, bạn có thể duyệt qua thư viện trưng bày của họ để xem dự án nào sử dụng Docsify cho tài liệu của họ.

Tất cả thông tin thiết lập cơ bản và tải tệp tin có thể được tìm thấy trên GitHub, do đó hãy đi qua đó nếu bạn muốn đưa ra cú đánh này.

Bạn cũng có thể xem demo trực tiếp trên trang tài liệu Docsify chính mà chắc chắn chạy trên Docsify. Vì vậy, nếu bạn thích bố cục trang web, bạn có thể sử dụng cùng một khuôn mẫu và chạy nó qua Docsify, 100% miễn phí và mã nguồn mở.

Markdown là gì?

Tui thường hay tải về nhiều thứ trên GitHub nhưng ít khi để ý tới các file *.md có sẵn trong đó, chỉ toàn coi document hay wiki ngay trực tiếp trên trình duyệt thôi, nay sẵn dịp nên cũng coi thử luôn đây là cái gì!

Là một ngôn ngữ đánh dấu, kiểu như là HTML hay XHTML, nhưng khá đơn giản và rất dễ đọc theo kiểu plain-text, nếu có điều kiện thì có thể chuyển đổi thành HTML để coi trên trình duyệt web với các định dạng đầy đủ đẹp mắt.

Đánh dấu tức là làm cho những chỗ muốn nhấn mạnh đậm lên, in nghiêng và có màu mè hoa lá hoặc hình ảnh để người đọc chú ý như bạn vừa thấy. Thực ra, có thể bạn chả cần quan tấm đến Markdown làm gì khi mà mấy cái trò vừa rồi bạn có thể dùng Word hay nếu biết lập trình thì dùng ngôn ngữ HTML, mà không biết lập trình cũng chả sao, dùng Adobe Dreamweaver/ Microsoft WebMatrix/ hay các tools online như Google Docs/ Microsoft Office Online đều làm rất dễ dàng và nhanh chóng với giao diện cực kỳ trực quan như là slogan của Firefox tiếng Việt hồi xưa vậy “Ngay cả mẹ cũng có thể lướt web dễ dàng” 😀 Nhưng mục đích ra đời của Markdown là giúp bạn có thể nhanh chóng ghi lại những điều cần thiết một cách nhanh chóng với đầy đủ định dạng đánh dấu như trên bằng plain-text được hỗ trợ trên bất kỳ môi trường nào.

Cú pháp cơ bản của Markdown

• *nghiêng* hoặc _nghiêng_ là nghiêng
• **đậm** hoặc __đậm__ là đậm
• [tên link](đường dẫn) là link
•  giống link nhưng cho ảnh
• # Chương 1, ## Mục 1, ### Mục 1.1

Để coi hết toàn bộ – cũng không nhiều lắm đâu – thì bạn vào một trong các link bên dưới:

– https://en.support.wordpress.com/markdown-quick-reference/ (Có ví dụ và minh họa kế bên, coi rất sướng)

– http://support.mashery.com/docs/customizing_your_portal/Markdown_Cheat_Sheet (Cũng có ví dụ và minh họa kế bên, cũng sướng như trên).

– https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet (Đây cũng là link của dự án Markdown Here, một phần mở rộng (extension) cho Chrome, Firefox, Safari, Opera, Thunderbird, Postbox giúp bạn có thể viết Markdown ngay trong chính các ứng dụng trên, rất thú vị).

– http://daringfireball.net/projects/markdown/syntax (Nằm trong trang chủ của dự án luôn nhưng coi không sướng bằng trang ở trên đâu!)

– Nếu muốn học tuần tự theo từng bài thì có trang http://markdowntutorial.com/

Ứng dụng

Từ bây giờ, ở bất cứ đâu bạn cần ghi chú đều có thể áp dụng Markdown để đánh dấu văn bản, sau đó sử dụng các chương trình để chuyển đổi sang định dạng dễ nhìn nếu cần thiết.

Ngoài ứng dụng cá nhân thì Markdown hiện tại còn được chính thức sử dụng trên github.com, stackoverflow.com, Atlassian Stash…: trong các file README.md, trong bất kỳ chỗ nào cần phải viết.

Bạn cũng có thể dùng để viết blog, chẳng hạn như đi du lịch ở đâu đó không có mạng thì có thể viết trên Notepad rồi sau đó post như bình thường. WordPress có hỗ trợ, nhưng bạn phải vào Settings> Writing và chọn Use Markdown for posts and pages.

Có nhiều chương trình online và offline có thể chuyển đổi Markdown:

http://dillinger.io/

MarkdownPad (có phiên bản miễn phí và bản Pro), hoặc http://typora.io/ một ứng dụng đang phát triển với tính năng live preview khi viết cũng khá hay.

Tương lai

Phần này bổ sung thêm, do trong quá trình Google tui có thấy một số bài viết nói về CommonMark (http://commonmark.org/) đặc tả cú pháp rõ ràng và tiêu chuẩn cho Markdown, Markdown A+ một giải pháp của người Việt để mở rộng khả năng của Markdown cho ngành xuất bản, đọc bài tại tinhte.vn thấy cũng hay nhưng không thấy website nào của nước ngoài nhắc đến không biết đã được công bố rộng rãi hay chưa.