Cách sử dụng Markdown nhanh chóng trên GitHub và Reddit

Informatec Digital » Recursos » Cách sử dụng Markdown nhanh chóng trên GitHub và Reddit

Nếu bạn thường xuyên viết bài trên GitHub hoặc dành nhiều thời gian trên Reddit, việc thành thạo Markdown là một trong những điều giúp bạn tiết kiệm hàng giờ và làm cho cuộc sống dễ dàng hơn. Đây là một ngôn ngữ đánh dấu rất nhẹ, cho phép bạn nhanh chóng định dạng văn bản thuần túy mà không cần phải loay hoay với menu hay nút bấm, chỉ cần đặt một vài ký hiệu vào đúng vị trí.

Trên GitHub, bạn sẽ thấy Markdown ở khắp mọi nơi: trong các tệp README.md của kho lưu trữ , các vấn đề, yêu cầu kéo, các cuộc thảo luận, và thậm chí cả trong hồ sơ cá nhân của bạn. Mặt khác, Reddit sử dụng một biến thể gọi là Snoomark (Markdown kiểu Reddit) kế thừa phần lớn cú pháp của GitHub, với một số tính năng và hạn chế riêng. Hãy cùng xem, từng bước một và với nhiều ví dụ, cách sử dụng Markdown trên GitHub và Reddit một cách nhanh chóng và không bỏ sót bất kỳ thông tin quan trọng nào.

Markdown là gì và tại sao nó lại hữu ích trên GitHub và Reddit?

Markdown là một ngôn ngữ đánh dấu nhẹ được thiết kế để giúp văn bản thuần túy dễ đọc và dễ viết, đồng thời cho phép chuyển đổi dễ dàng sang HTML. Trên thực tế, điều này có nghĩa là bạn có thể viết văn bản thông thường và thêm một vài ký tự đặc biệt để tạo tiêu đề, danh sách, bảng, trích dẫn, mã được định dạng, liên kết hoặc hình ảnh.

Trên GitHub, công cụ được sử dụng là GitHub Flavored Markdown (GFM), mở rộng cú pháp cổ điển với bảng, danh sách việc cần làm, tô sáng mã nâng cao, hỗ trợ màu sắc, cảnh báo và một số thẻ HTML được cho phép. Tất cả những điều này được tự động hiển thị trong các tệp .md và trong các trường bình luận của nền tảng.

Reddit sử dụng trình soạn thảo riêng của mình có tên là Snoomark, một phiên bản phái sinh từ GFM. Nó chia sẻ nhiều chức năng cơ bản (chữ đậm, chữ nghiêng, tiêu đề, danh sách, trích dẫn, mã nội tuyến hoặc khối, liên kết, v.v.), nhưng có những đặc điểm riêng quan trọng : ví dụ, khả năng hỗ trợ hình ảnh bị hạn chế hơn tùy thuộc vào ngữ cảnh, và nó bổ sung thêm các yếu tố riêng như spoiler.

Điều tuyệt vời của tất cả những điều này là, chỉ với một cú pháp duy nhất, bạn có thể viết các văn bản trông đẹp mắt trên cả GitHub và Reddit, chỉ cần điều chỉnh một vài chi tiết nhỏ ở những chỗ mỗi nền tảng hoạt động khác nhau. Nắm vững các quy tắc cơ bản cho phép bạn dễ dàng sử dụng cả hai mà không cần phải học lại từ đầu.

Cấu trúc tiêu đề và nội dung

Một trong những thứ đầu tiên bạn sẽ sử dụng là tiêu đề , cả trên GitHub và Reddit. Chúng giúp cấu trúc văn bản thành các phần và tiểu phần.

Trong Markdown, tiêu đề được tạo bằng cách đặt từ một đến sáu dấu thăng (#) trước văn bản: một dấu thăng cho tiêu đề cấp 1, hai dấu thăng cho tiêu đề cấp 2, và cứ thế cho đến cấp 6. Ví dụ, trong tệp README.md của GitHub, bạn có thể có nội dung như sau: # Tiêu đề chính , ## Phần , ### Tiểu mục , v.v.

Khi GitHub tìm thấy hai hoặc nhiều tiêu đề trong một tệp, nó sẽ tự động tạo mục lục có thể truy cập từ biểu tượng "Outline" ở đầu tệp. Mỗi tiêu đề xuất hiện dưới dạng một liên kết đưa bạn trực tiếp đến phần đó, rất hữu ích cho các tài liệu dài.

Ngoài ra, mỗi tiêu đề trở thành một liên kết nội bộ mà bạn có thể liên kết đến bằng một đoạn URL dựa trên văn bản tiêu đề. Để tạo đoạn URL đó, GitHub áp dụng các quy tắc rất cụ thể: chuyển đổi các chữ cái thành chữ thường, thay thế khoảng trắng bằng dấu gạch ngang, loại bỏ dấu câu và các ký tự định dạng (như chữ nghiêng), cắt bỏ khoảng trắng thừa và, nếu kết quả trùng khớp với một tiêu đề trước đó, sẽ thêm hậu tố số (-1, -2, v.v.) để làm cho nó duy nhất.

Điều này cho phép bạn thực hiện những việc như đặt một phần mẫu ## và sau đó liên kết đến nó từ một điểm khác trong tài liệu bằng một liên kết như (#sample-section) , hoặc thậm chí liên kết đến các phần có ký tự đặc biệt trong tiêu đề, vì GitHub tạo đoạn mã theo các quy tắc đó và cho phép truy cập bằng cùng một mẫu.

Nhấn mạnh, văn bản được tô sáng và trích dẫn

Markdown cho phép bạn làm nổi bật văn bản bằng nhiều hình thức nhấn mạnh khác nhau : in đậm, in nghiêng, gạch ngang, chỉ số dưới, chỉ số trên hoặc gạch chân. Trên GitHub, bảng kiểu điển hình sẽ trông giống như thế này, mặc dù chúng tôi đã tóm tắt nó ở đây bằng các thuật ngữ khác:

Để in đậm văn bản , hãy bao quanh nó bằng hai dấu hoa thị hoặc hai dấu gạch dưới; để in nghiêng, hãy sử dụng một dấu hoa thị hoặc một dấu gạch dưới; để gạch ngang, hãy sử dụng hai dấu ngã ở hai bên văn bản. Bạn cũng có thể kết hợp in đậm và in nghiêng lồng nhau, sử dụng ba dấu hoa thị để áp dụng cả hai cho toàn bộ đoạn văn bản, hoặc sử dụng các thẻ HTML như `<b>` _{cho ^{chỉ số dưới và chỉ số trên, và `<i>` cho gạch chân.}}

GitHub cũng cho phép bạn tạo trích dẫn khối bằng cách đặt ký hiệu lớn hơn (>) ở đầu dòng. Văn bản được trích dẫn sẽ hiển thị với một thanh dọc ở bên trái và có màu xám, giúp nó nổi bật rõ ràng. Bạn có thể có nhiều dòng trong cùng một trích dẫn khối, và thậm chí lồng các trích dẫn bằng cách thêm nhiều ký hiệu > ở đầu.

Một hình thức trích dẫn nâng cao độc đáo của GitHub là cảnh báo hoặc nhắc nhở . Nó sử dụng cùng cú pháp trích dẫn khối, nhưng dòng đầu tiên bao gồm một dấu hiệu đặc biệt để chỉ ra loại cảnh báo. Ví dụ, bạn có thể chỉ định `alert` cho thông tin hữu ích, `mẹo hữu ích`, `dữ liệu quan trọng`, `cảnh báo khẩn cấp` và `cảnh báo về rủi ro hoặc hậu quả tiêu cực`. GitHub hiển thị mỗi loại bằng một màu sắc và biểu tượng khác nhau, giúp làm nổi bật thông tin quan trọng trong tài liệu của bạn.

Reddit cũng hỗ trợ trích dẫn đơn giản bằng ký hiệu >, mặc dù thiếu hệ thống ping phong phú như của GitHub. Tuy nhiên, đây vẫn là một cách rất hữu ích để trả lời ai đó bằng cách trích dẫn một phần tin nhắn của họ mà không cần lặp lại toàn bộ.

Tô sáng mã, khối và màu sắc

Cả GitHub và Reddit đều cho phép bạn làm nổi bật các đoạn mã trong văn bản bằng cách sử dụng dấu ngoặc kép ngược (`). Đối với mã nội tuyến, bạn bao quanh từ hoặc lệnh bằng một dấu ngoặc kép ngược ở mỗi bên. Điều này rất lý tưởng để làm nổi bật, ví dụ, ` git status` trong một câu, làm rõ rằng đó là một lệnh.

Khi bạn muốn một khối mã độc lập, Markdown sử dụng ba dấu ngoặc kép ngược: bạn viết một dòng với ba dấu ngoặc kép ngược, sau đó viết mã trên các dòng riêng biệt, và kết thúc bằng ba dấu ngoặc kép ngược khác. Trên GitHub, nếu bạn cũng chỉ định ngôn ngữ ngay sau dấu ngoặc kép ngược đầu tiên, thì cú pháp sẽ được tô sáng với màu sắc và định dạng dành riêng cho ngôn ngữ đó.

GitHub cũng cung cấp một tính năng cụ thể để làm nổi bật các giá trị màu bên trong dấu ngoặc kép ngược. Nếu bạn nhập màu ở định dạng thập lục phân, RGB hoặc HSL giữa các dấu ngoặc kép ngược, nền tảng sẽ bao gồm một chỉ báo màu nhỏ bên cạnh văn bản. Ví dụ, nếu màu nền ở chế độ sáng là #ffffff và ở chế độ tối là #000000, việc làm nổi bật các mã này cho phép bạn nhanh chóng biết mã nào là mã nào.

Về hiển thị mã và bảng, GitHub cho phép bạn bật phông chữ đơn cách cố định trong tất cả các trường bình luận, giúp dễ dàng làm việc với văn bản kỹ thuật. Nếu bạn chỉnh sửa nhiều đoạn mã trong trình duyệt hoặc trong các trình soạn thảo như Visual Studio Code , việc bật tùy chọn này sẽ giúp căn chỉnh và khả năng đọc nhất quán hơn nhiều.

Reddit cũng hỗ trợ các khối mã với dấu ngoặc kép ngược, cả nội tuyến và khối, mặc dù việc sử dụng chúng ở đó tập trung nhiều hơn vào các đoạn mã ngắn hoặc mã giả hơn là tài liệu dài như của một kho lưu trữ.

Liên kết, neo và điều hướng nội bộ

Việc tạo liên kết trong Markdown rất đơn giản: bạn đặt văn bản cần hiển thị cho người dùng trong dấu ngoặc vuông và URL trong dấu ngoặc đơn. Cách này hoạt động trên cả GitHub và Reddit, và có thể được nâng cao bằng các phím tắt trên GitHub (ví dụ: sử dụng tổ hợp phím để nhanh chóng chuyển đổi văn bản đã chọn thành liên kết).

GitHub bổ sung một số tính năng liên quan đến điều hướng. Thứ nhất, nó cho phép bạn liên kết trực tiếp đến các tiêu đề bằng cách sử dụng các quy tắc tạo đoạn mã đã được thảo luận trước đó. Thứ hai, nó hỗ trợ các liên kết tương đối trong chính kho lưu trữ, điều này rất quan trọng đối với tài liệu kỹ thuật.

Liên kết tương đối là liên kết được tính toán bằng cách sử dụng tệp hiện tại làm tham chiếu. Ví dụ, nếu tệp README của bạn nằm ở thư mục gốc của dự án và bạn muốn liên kết đến tệp docs/CONTRIBUTING.md, bạn chỉ cần viết một liên kết với đường dẫn docs/CONTRIBUTING.md. GitHub sẽ xử lý việc dịch liên kết tương đối này một cách chính xác trên bất kỳ nhánh nào bạn đang sử dụng, ngăn ngừa việc liên kết bị lỗi khi chuyển đổi nhánh hoặc sao chép kho lưu trữ.

Lời khuyên là luôn sử dụng đường dẫn tương đối khi điều hướng giữa các tệp trong cùng một kho lưu trữ, vì các liên kết tuyệt đối có thể ngừng hoạt động trong các bản sao hoặc nhánh. GitHub cho phép sử dụng các toán tử tiêu chuẩn như ./ hoặc ../ và các đường dẫn bắt đầu bằng / tương đối so với thư mục gốc của dự án.

Nếu bạn muốn tạo các điểm neo tùy chỉnh trong tài liệu ngoài các tiêu đề, bạn có thể sử dụng thẻ HTML với thuộc tính `name`. Điều này cho phép bạn đặt một điểm đích ở giữa đoạn văn hoặc bên cạnh văn bản không có tiêu đề riêng, và liên kết đến nó bằng cú pháp tương tự như đối với các tiêu đề được tạo tự động.

Hình ảnh trên GitHub: Định dạng Markdown, HTML và đường dẫn tương đối.

Trên GitHub, hình ảnh thường được nhúng bằng cú pháp tương tự như liên kết, nhưng có thêm dấu chấm than phía trước. Văn bản thay thế (alt) được chỉ định trong dấu ngoặc vuông, và URL hoặc đường dẫn đến hình ảnh được đặt trong dấu ngoặc đơn. Văn bản thay thế này rất quan trọng đối với khả năng truy cập , vì đây là những gì trình đọc màn hình sẽ đọc và sẽ được hiển thị nếu hình ảnh không tải được.

Hình ảnh có thể được lấy từ các tệp bên trong kho lưu trữ hoặc từ các URL bên ngoài. GitHub cho phép nhiều kiểu đường dẫn tương đối để tải lên hình ảnh từ các nhánh khác nhau, các kho lưu trữ khác, hoặc thậm chí cả các vấn đề và bình luận, sử dụng các hậu tố như ?raw=true để buộc tải xuống tệp trực tiếp khi cần thiết.

Ngoài cú pháp Markdown chuẩn, GitHub còn hỗ trợ sử dụng phần tử HTML `<picture>`. Phần tử này đặc biệt hữu ích để tải các hình ảnh đáp ứng , thay đổi theo tùy chọn chủ đề của người dùng (sáng hoặc tối). Sử dụng truy vấn phương tiện `prefers-color-scheme`, bạn có thể xác định các nguồn hình ảnh khác nhau cho mỗi chế độ và một hình ảnh mặc định cho các trình duyệt không hỗ trợ tính năng này.

Mô hình điển hình bao gồm việc bao gồm bên trong một số yếu tố với các thuộc tính media và srcset của nó, và cuối cùng là một Bằng cách sử dụng thuộc tính alt và URL chung, người dùng ở chế độ tối sẽ thấy hình ảnh được điều chỉnh, trong khi người dùng ở chế độ sáng sẽ nhận được một hình ảnh khác, mà không cần phải sao chép nội dung trong tệp README.

GitHub cũng hỗ trợ chú thích HTML trong các tệp Markdown, cho phép bạn thêm những lời nhắc nhở ẩn cho người đọc, ví dụ như nhắc họ cập nhật phần hình ảnh hoặc thêm ví dụ mới sau này.

Bảng biểu, các phần gấp mở và phân tách nội dung

Một trong những cải tiến hữu ích nhất của GitHub Flavored Markdown là khả năng hỗ trợ bảng . Bạn có thể sắp xếp dữ liệu thành các hàng và cột bằng cách sử dụng các dấu gạch dọc để phân tách các ô và một hàng dấu gạch ngang để đánh dấu tiêu đề. Bạn cũng có thể căn chỉnh các cột sang phải, trái hoặc giữa bằng cách sử dụng dấu hai chấm trong hàng phân cách.

Bảng biểu rất hữu ích để trình bày danh sách các ngôn ngữ lập trình, framework được sử dụng, các nhiệm vụ đã lên kế hoạch, so sánh tính năng hoặc bất kỳ thông tin nào khác có thể được thể hiện dưới dạng ma trận. GitHub hiển thị các bảng này với kiểu dáng gọn gàng và dễ đọc.

Để giữ cho tệp README dài được sắp xếp gọn gàng, bạn có thể sử dụng thẻ HTML `<details>` để tạo các phần có thể thu gọn. Các phần này hiển thị tóm tắt bên trong thẻ `<summary>` và cho phép người dùng mở rộng hoặc thu gọn nội dung bổ sung khi cần. Thông thường, người ta sẽ đặt các bảng hoặc các khối thông tin phụ bên trong thẻ `<details>` để tránh làm người dùng choáng ngợp ngay từ cái nhìn đầu tiên.

Nếu bạn muốn phần này hiển thị mở rộng theo mặc định, chỉ cần thêm thuộc tính open vào Kỹ thuật này rất thiết thực để nhóm các bảng xếp hạng, danh sách dài hoặc nội dung không thiết yếu cho lần đọc đầu tiên nhưng lại thuận tiện để truy cập.

Một công cụ đơn giản khác để sắp xếp thông tin là đường kẻ ngang. Nó được tạo ra bằng cách viết ba hoặc nhiều dấu gạch ngang trên một đường thẳng và dùng để vạch ra ranh giới giữa các phần, cho phép bạn phân tách rõ ràng, ví dụ, phần mô tả với phần tài liệu tham khảo hoặc ghi chú bổ sung.

Những quy tắc này có thể được kết hợp với các trích dẫn cuối tài liệu để làm nổi bật những câu nói truyền cảm hứng, lời nhắc nhở hoặc thông điệp quan trọng. Một ví dụ điển hình là đặt một câu trích dẫn tạo động lực ở cuối tệp README hồ sơ của bạn, được định dạng bằng trích dẫn khối sau một dòng phân cách.

Chú thích ẩn và kiểm soát định dạng

GitHub cho phép bạn chèn nhận xét HTML vào trong Markdown bằng cú pháp <!-- comment -->. Bất cứ thứ gì bạn viết bên trong nhận xét đó sẽ không được hiển thị trong nội dung đã render, nhưng nó sẽ hiển thị trong mã nguồn, rất lý tưởng cho các ghi chú nội bộ hoặc việc cần làm.

Ví dụ, trong tệp README của hồ sơ, bạn có thể thêm một bình luận nói rằng bạn cần mở rộng phần "Giới thiệu về tôi" sau này hoặc bạn cần xem lại bảng các công nghệ lỗi thời, mà không cần bất kỳ ai truy cập hồ sơ đó nhìn thấy trực tiếp.

Một tính năng hữu ích khác là khả năng thoát các ký tự thường được hiểu là định dạng Markdown. Nếu bạn cần hiển thị dấu sao, dấu thăng hoặc các ký hiệu khác mà không cần định dạng, chỉ cần thêm dấu gạch chéo ngược trước mỗi ký hiệu. Điều này cho phép bạn, ví dụ, viết các biểu thức bao gồm các ký hiệu danh sách mà không cần chuyển đổi chúng thành danh sách thực sự.

Khi xem một tệp đánh dấu trên GitHub, bạn có tùy chọn chuyển đổi giữa chế độ xem đã hiển thị và mã nguồn bằng một nút ở phía trên (hoặc mở nó trong các trình soạn thảo như Brackets ). Việc tắt tính năng diễn giải Markdown cho phép bạn truy cập các tính năng xem mã thông thường như liên kết các dòng cụ thể , điều này rất hữu ích khi bạn muốn làm nổi bật một phần cụ thể của tệp README hoặc bất kỳ tệp .md nào.

Cuối cùng, hãy nhớ rằng GitHub xử lý ngắt dòng khác nhau trong phần bình luận (vấn đề, yêu cầu kéo, v.v.) và trong các tệp .md. Trong phần bình luận, dấu ngắt dòng được tuân thủ trực tiếp, trong khi ở các tệp Markdown, bạn cần thêm hai dấu cách ở cuối dòng, một dấu gạch chéo ngược hoặc một dấu chấm. Để buộc nhảy đoạn văn ngay trong cùng một đoạn.

Danh sách, danh sách lồng nhau và danh sách việc cần làm

Danh sách là một trong những phần tử được sử dụng phổ biến nhất trong Markdown, cả trên GitHub và Reddit. Bạn có thể tạo danh sách không thứ tự bằng cách đặt dấu gạch ngang, dấu sao hoặc dấu cộng trước mỗi mục trong danh sách. Tất cả các ký hiệu này đều hiển thị tương tự như dấu chấm đầu dòng.

Để tạo danh sách có thứ tự , hãy đánh số mỗi dòng bằng một số, theo sau là dấu chấm và một khoảng trắng. Mặc dù thứ tự các số không cần phải hoàn hảo (GitHub thường tính toán lại), nhưng việc duy trì số thứ tự nhất quán sẽ giúp mã nguồn dễ đọc hơn.

Danh sách lồng nhau được tạo đơn giản bằng cách thụt lề các mục bên dưới chúng. Trong các trình soạn thảo phông chữ đơn cách như Sublime Text , bạn chỉ cần căn chỉnh trực quan các dấu hiệu danh sách lồng nhau bên dưới ký tự đầu tiên của văn bản trong mục cha. Trong các ngữ cảnh như trình soạn thảo bình luận của GitHub, nơi phông chữ không phải là đơn cách, bạn nên đếm số ký tự trước văn bản và sử dụng số khoảng trắng đó để thụt lề.

Bạn cũng có thể tạo nhiều cấp độ lồng nhau, miễn là duy trì sự nhất quán về số lượng khoảng trắng. Đối với các danh sách rất phức tạp, hệ thống này cần một chút luyện tập, nhưng một khi đã nắm vững, việc áp dụng sẽ rất nhanh chóng.

GitHub cũng cung cấp danh sách tác vụ , rất hữu ích cho các vấn đề, yêu cầu kéo và tài liệu. Chúng được tạo bằng cách thêm dấu gạch ngang, dấu cách và một cặp dấu ngoặc vuông có dấu cách hoặc dấu "x" bên trong: một cho các tác vụ đang chờ xử lý và một cho các tác vụ đã hoàn thành. Các danh sách này được hiển thị với các hộp kiểm có thể được chọn hoặc bỏ chọn từ giao diện.

Nếu văn bản của một mục trong danh sách việc cần làm bắt đầu bằng dấu ngoặc đơn, nó phải được thoát bằng dấu gạch chéo ngược để tránh nhầm lẫn trong trình phân tích cú pháp. Đó là một chi tiết nhỏ nhưng quan trọng khi viết các mô tả bắt đầu bằng những cụm từ như "(Tùy chọn)" hoặc tương tự.

Các đề cập, tham chiếu và biểu tượng cảm xúc trên GitHub

Một trong những ưu điểm của việc viết bằng Markdown trên GitHub là khả năng nhắc trực tiếp đến người dùng và nhóm trên nền tảng này. Bạn chỉ cần gõ @ theo sau là tên người dùng hoặc tên nhóm, và GitHub sẽ gửi thông báo đến tài khoản đó, thu hút sự chú ý của họ đến cuộc trò chuyện.

Khi bạn gõ ký hiệu @, GitHub sẽ hiển thị danh sách người dùng và nhóm liên kết với kho lưu trữ hoặc luồng thảo luận, và bạn có thể lọc danh sách này khi đang gõ. Sử dụng các phím mũi tên và nhấn Enter hoặc Tab để chấp nhận các đề xuất. Đối với nhóm, hãy sử dụng định dạng @tổ chức/tên-nhóm, và tất cả thành viên nhóm sẽ được đăng ký theo dõi luồng thảo luận.

Ngoài tính năng nhắc đến người dùng, GitHub còn giúp bạn dễ dàng tham chiếu các vấn đề và yêu cầu kéo (pull request) chỉ bằng cách gõ # theo sau là một số hoặc một phần tiêu đề. Một danh sách các kết quả được đề xuất sẽ hiện ra, và bạn có thể hoàn thành chúng theo cách tương tự như với tính năng nhắc đến người dùng. Điều này giúp tăng tốc đáng kể việc điều hướng giữa các cuộc hội thoại liên quan.

Nếu kho lưu trữ của bạn đã cấu hình các tham chiếu tự động liên kết tùy chỉnh, một số ký hiệu bên ngoài (chẳng hạn như ID vé JIRA hoặc Zendesk) cũng có thể được tự động chuyển đổi thành liên kết rút gọn. Cài đặt này yêu cầu quyền quản trị, nhưng sau khi được kích hoạt, nó cho phép chia sẻ dữ liệu giữa các hệ thống với nỗ lực tối thiểu.

Cuối cùng, GitHub hỗ trợ biểu tượng cảm xúc thông qua mã: gõ dấu hai chấm, theo sau là tên biểu tượng cảm xúc, và kết thúc bằng một dấu hai chấm khác. Khi bạn bắt đầu gõ, một danh sách các gợi ý sẽ hiện ra, bạn có thể chấp nhận bằng phím Tab hoặc Enter. Việc kết hợp biểu tượng cảm xúc vào bình luận giúp chúng trở nên gần gũi hơn, miễn là bạn không lạm dụng chúng trong tài liệu chính thức.

Chú thích và nội dung nâng cao

GitHub cũng hỗ trợ chú thích cuối trang bằng cú pháp dựa trên dấu ngoặc và một định danh có ký tự mũ. Tại vị trí bạn muốn tham chiếu, bạn chèn một cái gì đó như `<chú thích>`, và ở cuối tài liệu, bạn xác định văn bản của chú thích đó bằng cùng một thẻ, theo sau là dấu hai chấm và nội dung.

Chú thích cuối trang có thể trải dài nhiều dòng, và để buộc xuống dòng trong chú thích, khoảng trắng kép được sử dụng ở cuối dòng, giống như trong phần nội dung chính của Markdown. Khi hiển thị, GitHub sẽ hiển thị chỉ số trên đầu văn bản và danh sách chú thích ở cuối, với các liên kết ngược để điều hướng giữa các tài liệu tham khảo và chú thích.

Một tính năng nâng cao khác mà GitHub cung cấp là các cảnh báo đã đề cập trước đó (NOTE, TIP, IMPORTANT, WARNING và CAUTION). Nên sử dụng chúng chỉ khi thực sự cần thiết và tránh kết hợp quá nhiều để không làm người đọc bị choáng ngợp. Chúng không thể được lồng ghép trong các yếu tố phức tạp khác, vì vậy việc lập kế hoạch cẩn thận cho vị trí đặt chúng là rất quan trọng.

Cuối cùng, bạn có thể yêu cầu GitHub tạm thời ẩn các phần của Markdown đã được hiển thị bằng cách bao bọc chúng trong các bình luận HTML, hoặc bỏ qua việc xử lý một số ký tự nhất định bằng dấu gạch chéo ngược. Điều này đặc biệt hữu ích khi bạn đang ghi lại cú pháp Markdown và cần hiển thị các ví dụ nguyên trạng, không cần diễn giải.

Markdown trên Reddit: Snoomark và chế độ chỉnh sửa

Reddit là một nền tảng thảo luận nơi hầu hết mọi chủ đề đều được chào đón, được tổ chức thành các subreddit. Về định dạng, nó cung cấp hai trình soạn thảo: một dành cho văn bản đa dạng, trực quan hơn, và một dành cho văn bản thuần túy dựa trên Markdown. Nếu bạn muốn làm việc nhanh chóng và kiểm soát kết quả một cách chính xác, bạn nên sử dụng tùy chọn Markdown.

Theo mặc định, Reddit thường kích hoạt trình soạn thảo văn bản đa dạng, vì vậy để chuyển sang chế độ đánh dấu, bạn phải nhấp vào tùy chọn Chế độ Markdown trong hộp văn bản của bài đăng hoặc bình luận. Từ đó, bạn có thể sử dụng cú pháp Snoomark trực tiếp.

Nếu bạn muốn trình soạn thảo Markdown luôn được tải, hãy vào cài đặt người dùng, vào mục Cài đặt nguồn cấp dữ liệu và bật tùy chọn "Mặc định là Markdown" . Bằng cách này, trình soạn thảo Markdown sẽ tự động mở mỗi khi bạn bắt đầu viết bài đăng hoặc bình luận, mà không cần bạn phải thay đổi thủ công.

Reddit hỗ trợ hầu hết các tính năng cơ bản và nâng cao của Markdown: tiêu đề, chữ đậm và chữ nghiêng, danh sách, trích dẫn, khối mã, liên kết và một số tính năng bổ sung riêng như spoiler. Tuy nhiên, nó có những hạn chế đáng kể so với GitHub, đặc biệt là trong việc xử lý hình ảnh , vốn phụ thuộc rất nhiều vào ngữ cảnh và loại trình soạn thảo.

Cú pháp được hỗ trợ bởi Reddit và spoilers

Biến thể Snoomark được Reddit sử dụng bao gồm nhiều yếu tố tương đồng với GitHub, vì vậy nếu bạn đã thành thạo Markdown cho các kho lưu trữ, việc chuyển giao kiến ​​thức đó sang môi trường Reddit khá đơn giản. Bạn có thể sử dụng tiêu đề để cấu trúc các bài đăng dài, danh sách đánh số hoặc gạch đầu dòng, trích dẫn để trả lời người dùng khác và khối mã khi bạn muốn hiển thị các lệnh hoặc đoạn mã kỹ thuật.

Một trong những điểm khác biệt đáng chú ý là cách Reddit xử lý hình ảnh . Mặc dù trong nhiều trường hợp, hình ảnh được tải lên thông qua giao diện đồ họa chứ không phải trực tiếp bằng cú pháp Markdown, nhưng công cụ xử lý nội dung văn bản vẫn là Snoomark, vì vậy định dạng xung quanh những hình ảnh đó thực sự dựa trên Markdown.

Mặt khác, Reddit bổ sung thêm các tính năng không có trong tiêu chuẩn thông thường, chẳng hạn như spoiler. Tính năng này cho phép ẩn văn bản phía sau một lớp mà người dùng có thể hiển thị bằng một cú nhấp chuột. Về mặt kỹ thuật, khi Reddit xử lý một spoiler, nó sẽ chuyển đổi spoiler đó thành sự kết hợp của HTML, các lớp CSS và JavaScript dành riêng cho nền tảng.

Kết quả hiển thị HTML của một spoiler bao gồm các trình xử lý điều khiển việc hiển thị hoặc ẩn nội dung, và mặc dù về mặt lý thuyết, điều tương tự có thể được viết bằng HTML thuần túy, nhưng trên Reddit, điều đó phụ thuộc vào cách triển khai nội bộ của nó. Điều quan trọng đối với bạn với tư cách là người dùng là, khi viết, bạn chỉ cần sử dụng cú pháp spoiler cụ thể do trình soạn thảo cung cấp, và Snoomark sẽ lo việc dịch nó thành cấu trúc phù hợp.

Tóm lại, Snoomark thừa hưởng nhiều đặc điểm từ GitHub Flavored Markdown, nhưng được điều chỉnh phù hợp với nhu cầu của cộng đồng thảo luận hơn là tài liệu dự án. Tuy nhiên, cốt lõi vẫn giữ nguyên: văn bản thuần túy với các ký hiệu đơn giản được chuyển đổi thành nội dung có cấu trúc và dễ đọc.

Nắm vững cú pháp Markdown trên GitHub và Reddit giúp việc viết tài liệu kỹ thuật, mở các vấn đề được giải thích rõ ràng, để lại bình luận mạch lạc trên các yêu cầu kéo (pull request) và tham gia thảo luận trên Reddit hiệu quả hơn rất nhiều. Với một vài quy tắc chính—tiêu đề, nhấn mạnh, danh sách, trích dẫn, khối mã, liên kết, hình ảnh và các thủ thuật cụ thể như bảng, chi tiết thu gọn, cảnh báo, chú thích cuối trang và spoiler—bạn có thể chuyển từ việc viết những thông điệp nhàm chán sang tạo ra nội dung sạch sẽ, dễ đọc lướt và chuyên nghiệp mà không cần nhấp chuột một lần nào.