如何在 GitHub 和 Reddit 上快速使用 Markdown

資訊科技數位 » recursos » 如何在 GitHub 和 Reddit 上快速使用 Markdown

如果你經常在 GitHub 上寫程式碼或花很多時間在 Reddit 上，那麼掌握以下技能至關重要： 降價 它能幫你節省很多時間，讓你的生活更輕鬆。它是一種非常輕量級的標記語言，只需在正確的位置放置幾個符號，就能讓你快速格式化純文本，無需費力處理菜單或按鈕。

在 GitHub 上，你到處都能找到它：在文件中 README.md 程式碼可以來自倉庫、問題、拉取請求、討論，甚至你自己的個人資料。 Reddit 則使用名為 Snoomark（Reddit 風格的 Markdown）的變體，它繼承了 GitHub 的大部分語法，但也具有一些獨特的功能和一定的限制。讓我們一步一步地透過大量範例來了解一下。 如何在 GitHub 和 Reddit 上快速使用 Markdown 而且沒有遺漏任何重要內容。

什麼是 Markdown？為什麼它在 GitHub 和 Reddit 上如此有用？

降價是一個 輕量級標記語言 旨在讓純文字易於閱讀和編寫，同時也能輕鬆轉換為 HTML。實際上，這意味著您可以編寫普通文字並添加特殊字元來建立標題、清單、表格、引用、格式化程式碼、連結或圖像。

在 GitHub 上，使用的實作方式是 GitHub Flavored Markdown (GFM)，它在經典語法的基礎上擴展了表格、待辦事項清單、高級程式碼高亮顯示、色彩支援、警告和一些允許的 HTML 標籤。 所有這些都是自動渲染的。 在 .md 檔案和平台的評論欄位中。

Reddit 使用名為 Snoomark 的自有處理器，它是 GFM 的衍生產品。它與 GFM 共享許多基本功能（粗體、斜體、標題、列表、引用、行內或區塊級程式碼、連結等），但它也有一些不同之處。 重要特徵例如，圖像支援會因上下文而異，並添加劇透等元素。

這一切的妙處在於，只需使用單一語法，您就可以編寫在 GitHub 和 Reddit 上都看起來不錯的文本，只需針對每個平台不同的一些細節進行調整即可。 學習基本規則 它讓你可以在兩者之間自由移動，而無需從頭開始重新學習任何東西。

標題和內容結構

你首先要用到的東西之一是 標題在 GitHub 和 Reddit 上，它們都用於將文本組織成章節和子章節。

在 Markdown 中，標題透過在文字前面加上一到六個井號 (#) 來建立：一個井號表示一級標題，兩個井號表示二級標題，依此類推，直到六級標題。例如，在 GitHub 的 README.md 檔案中，您可能會看到類似這樣的內容： # 主標題, ＃＃ 部分, ### 小節等等。

當 GitHub 在一個檔案中發現兩個或多個頭部資訊時，它會自動產生一個 目錄 可透過文件頂部的「大綱」圖示存取。每個標題都以連結的形式顯示，點擊即可直接跳到相應部分，這對於長文件非常有用。

此外，每個標題都會成為一個內部錨點，您可以根據標題文字產生 URL 片段並連結到該錨點。為了產生該片段，GitHub 應用了非常具體的規則：它將字母轉換為小寫，將空格替換為連字符，移除標點符號和格式字符（例如斜體），去除多餘的空格，並且，如果結果與之前的另一個標題匹配， 添加數字後綴 （-1、-2 等）使其唯一。

這樣你就可以執行諸如放置一個部分之類的操作。 ## 範例部分 然後從文檔中的其他位置使用類似這樣的連結連結到它： （#範例部分）甚至可以連結到標題中包含特殊字元的部分，因為 GitHub 會按照這些規則產生程式碼片段，並以相同的模式使其可訪問。

強調、高亮文字和引文

Markdown 可讓您使用各種方法來突出顯示文字。 重點粗體、斜體、刪除線、下標、上標或底線。在 GitHub 上，典型的樣式表如下所示，不過我們在這裡用不同的字詞對其進行了概括：

在文字中輸入 黑體字粗體文字用雙星號或雙底線括起來；斜體文字用單星號或單底線括起來；刪除線則用雙波浪號（兩個波浪號）分別放在文字兩側。粗體和斜體可以組合使用，也可以用三個星號將粗體和斜體應用於整段文本，或使用HTML標籤，例如<br>。 _{y ^{對於下標和上標，以及 用於加下劃線。}}

GitHub 還允許您創建 塊引用樣式 在行首加上大於號 (>)，引用的文字左側會顯示一條灰色垂直線，使其清晰醒目。同一個引用區塊可以包含多行，甚至可以透過在行首添加更多 > 符號來嵌套引用。

GitHub 上有一種高階引用形式： 警告或告誡它們基於相同的引用區塊語法，但第一行包含一個特殊標記，用於指示警報類型。例如，您可以指定 `<alert>` 用於實用訊息，`<helpful tips>` 用於實用建議，`<key data>` 用於關鍵數據，`<urgent notices>` 用於緊急警告，以及 `<alert>` 用於風險或負面後果警告。 GitHub 會使用不同的顏色和圖示顯示每種類型，從而幫助突出顯示文件中的關鍵資訊。

Reddit 也支援使用相同的符號 > 進行簡單引用，儘管它缺少 GitHub 那樣豐富的警告系統。即便如此，它仍然是一種非常實用的方式。 回覆他人時引用對方的部分訊息 無需完全重複。

程式碼高亮、程式碼區塊和顏色

GitHub 和 Reddit 都允許你使用反引號高亮顯示文字中的程式碼片段。對於行內程式碼，你需要用一個反引號將單字或指令括起來。這非常適合高亮顯示例如… git狀態 在句子中明確表明這是一個命令。

當您需要一段獨立的程式碼區塊時，Markdown 使用三個反引號：您用三個反引號開始一行，然後在單獨的行中編寫程式碼，最後再用三個反引號結束。在 GitHub 上，如果您在第一個反引號後緊接著指定語言，則會自動套用… 語法高亮 採用該語言特有的顏色和格式。

GitHub 還提供了一個專門用於突出顯示的功能。 顏色值 在反引號內輸入顏色值。如果您在反引號內以十六進位、RGB 或 HSL 格式輸入色彩值，平台會在文字旁邊顯示一個小的顏色指標。例如，如果淺色模式下的背景色是 #ffffff，深色模式下是 #000000，高亮顯示這些程式碼可以讓您快速區分哪個是哪個。

關於程式碼和表格視覺化，GitHub 允許您在所有註解欄位中啟用等寬字體，以便更舒適地處理技術文字。如果您經常在瀏覽器或類似編輯器中編輯大量程式碼片段，那麼啟用等寬字體會更加方便。 Visual Studio代碼啟用此選項可使對齊和閱讀更加容易。 更加連貫.

Reddit 也支援使用反引號的程式碼區塊，包括行內程式碼區塊和區塊級程式碼區塊，儘管它們在那裡更多地用於小的程式碼片段或偽程式碼，而不是像儲存庫那樣的長篇文件。

連結、錨點和內部導航

在 Markdown 中建立連結非常簡單：只需將要顯示給使用者的文字放在方括號中，將 URL 放在圓括號中即可。這種方法在 GitHub 和 Reddit 上都適用，並且在 GitHub 上還可以透過鍵盤快速鍵進行增強（例如，使用組合鍵快速將選定的文字轉換為連結）。

GitHub 增加了一些與導航相關的額外功能。例如，它允許… 直接連結到標題 它採用了前面討論過的片段生成規則。此外，它還支援儲存庫內部的相對鏈接，這對於技術文件至關重要。

相對連結是指以目前文件為參考計算的連結。例如，如果您的 README 文件位於專案根目錄，而您想要連結到 docs/CONTRIBUTING.md 文件，您只需編寫一個路徑為 docs/CONTRIBUTING.md 的連結即可。 GitHub 會在您目前所在的任何分支中正確轉換此相對鏈接，從而防止在切換分支或克隆倉庫時鏈接失效。

建議始終使用 相對路徑 為了在同一儲存庫中的檔案之間導航，因為絕對連結在複製或分支中可能會停止工作，GitHub 允許使用標準運算符，例如 ./ 或 ../ 以及相對於專案根目錄的以 / 開頭的路徑。

如果想要在文件中建立標題以外的自訂錨點，可以使用帶有 `name` 屬性的 HTML 標籤。這樣，您可以將目標點放置在段落中間或沒有標題的文字旁邊，並使用與自動產生的標題相同的語法連結到該錨點。

GitHub 上的圖片：Markdown、HTML 與相對路徑

在 GitHub 上，圖片通常使用與連結相同的語法嵌入，但前面要加一個感嘆號。替代文字（alt）放在方括號內，圖片的 URL 或路徑放在圓括號內。此替代文字對於…非常重要。 可訪問性因為螢幕閱讀器會讀取這些內容，如果圖像無法加載，也會顯示這些內容。

圖片可以來自倉庫內部的文件，也可以來自外部 URL。 GitHub 允許使用多種相對路徑模式，從不同的分支、其他倉庫，甚至是 issue 和評論中上傳圖片，並使用諸如 `.htm` 之類的後綴。 ?raw=true 必要時強制直接下載檔案。

除了標準的 Markdown 語法外，GitHub 還支援使用 HTML 元素這個物品特別適合充電。 響應式影像 這些會根據使用者的主題偏好（淺色或深色）而變化。使用媒體查詢 `prefers-color-scheme`，您可以為每種模式定義不同的影像來源，並為不支援此功能的瀏覽器定義預設影像。

典型模式包括包含在內幾個要素及其媒體和 srcset 屬性，最後是一個使用 alt 屬性和通用 URL，深色模式的使用者可以看到調整後的影像，而淺色模式中的使用者可以看到不同的影像，而無需在 README 中重複內容。

GitHub 還支援 Markdown 文件中的 HTML 註釋，讓您可以為讀者添加不可見的提醒，例如提醒他們稍後更新圖片部分或添加新範例。

表格、摺頁和內容分隔

GitHub Flavored Markdown 中最有用的改進之一是它對以下功能的支援： 桌子您可以使用垂直線分隔單元格，用虛線標記標題，將資料整理成行和列。您也可以使用分隔符號中的冒號將列右對齊、左對齊或居中對齊。

表格非常適合用來展示程式語言清單、使用的框架、規劃任務、功能對比，或任何其他適合矩陣結構的資訊。 GitHub 以簡潔易讀的樣式呈現這些表格。

為了保持較長的 README 文件條理清晰，您可以使用 HTML 標籤。建立可折疊部分。這些部分在標籤內顯示摘要。並允許使用者展開或收縮 附加內容 根據需要。通常會將表格或輔助資訊區塊包含在內。避免眼睛感到疲倦。

如果您希望該部分預設展開顯示，只需新增 open 屬性即可。這種方法非常適用於將排名、長列表或對於初次閱讀來說並非必不可少但便於存取的內容進行分組。

另一個簡單的整理資訊的工具是水平線。它由三個或更多短橫線組成，用於劃分各個部分，例如，可以清晰地將描述性部分與參考文獻或補充說明部分分開。

這些規則可以與文件末尾引用結合使用，以突出顯示勵志短語、提醒事項或關鍵資訊。一個典型的例子是在個人資料 README 文件的末尾放置一句勵志名言，並以分隔符號後插入一段引用文字。

隱藏註解和格式控制

GitHub 讓你介紹 HTML 註釋 在 Markdown 中使用語法註釋中的內容不會顯示在渲染後的內容中，但會在原始程式碼中可見，因此非常適合用於內部筆記或待辦事項。

例如，在個人資料的 README 文件中，您可以添加一條評論，說明您需要稍後擴展“關於我”部分，或者您需要查看過時技術表，而無需讓訪問該個人資料的任何人直接看到它。

另一個有用的功能是 轉義字符 這通常會被解讀為 Markdown 格式。如果您需要直接顯示星號、井號或其他符號而不進行格式化，只需在每個符號前加上反斜線即可。例如，這樣您就可以編寫包含列表符號的表達式，而無需將其轉換為實際的清單。

在 GitHub 上查看標記檔案時，您可以透過頂部的按鈕在渲染視圖和原始程式碼之間切換（或在編輯器中開啟它）。 括號停用 Markdown 解析後，您可以存取典型的程式碼視圖功能，例如 連結特定行當您想要指向 README 或任何 .md 檔案的確切部分時，這非常有用。

最後，請記住 GitHub 對評論（issue、PR 等）和 .md 檔案中的換行符處理方式不同。在評論中，換行符號會直接保留；而在 Markdown 檔案中，您需要在行尾添加兩個空格、一個反斜線或一個句點。強制在同一段落內跳轉。

列表、巢狀清單和待辦事項列表

清單是 Markdown 中最常用的元素之一，無論是在 GitHub 還是 Reddit 上都是如此。您可以建立清單。 無序 在每個清單項目前面加上連字號、星號或加號即可。所有這些標記都會以類似的方式顯示為項目符號。

產生列表 下令每行程式碼都用一個數字、一個句點和一個空格進行編號。雖然數字順序不必完全一致（GitHub 通常會自動重新計算），但為了提高原始程式碼的可讀性，最好保持編號的一致性。

嵌套清單的建立方法很簡單，只需為下面的項目新增縮排即可。在等寬字體編輯器中，例如 崇高的文字只需將嵌套列表標記在視覺上與父元素文字的第一個字元對齊即可。在像 GitHub 評論編輯器這樣字體不是等寬字體的環境中，請計算文字之前的字元數，並使用相同數量的空格進行縮排。

只要保持空格數量一致，你也可以建立多層嵌套。對於非常複雜的列表，這種方法需要一些練習，但一旦掌握了技巧，應用起來就非常快速。

GitHub 也提供 待辦事項清單這些清單對於問題、拉取請求和文件都非常有用。建立方法是在清單前加上一個連字符、一個空格，然後是一對方括號，方括號內可以加一個空格或一個「x」：表示待處理任務，表示已完成任務。這些清單會以複選框的形式呈現，可以在介面中選取或取消選取。

如果待辦事項清單項目的文字以括號開頭，則必須使用反斜線進行轉義，以避免解析器出現混淆。這是一個小細節，但在編寫以“（可選）”或類似內容開頭的描述時非常重要。

GitHub 上的提及、引用和表情符號

在 GitHub 上使用 Markdown 編寫程式碼的優點之一是能夠使用 提到 直接向平台上的用戶和團隊發送訊息。只需輸入 @ 符號，後面跟著使用者名稱或團隊名稱，GitHub 就會向該帳戶發送通知，吸引他們追蹤對話。

輸入 @ 符號後，GitHub 會顯示與該倉庫或主題關聯的使用者和團隊列表，您可以在輸入時篩選此列表。使用方向鍵並按 Enter 或 Tab 鍵接受建議。對於團隊，請使用 @組織/團隊名稱 的格式，所有團隊成員都將訂閱該主題。

除了提及之外，GitHub 還促進了 參考問題和拉取請求 只需輸入 # 號，後面跟著數字或部分標題。系統會顯示建議結果列表，您可以像新增提及一樣補充完整。這大大加快了在相關對話之間切換的速度。

如果您的程式碼庫配置了自訂自動連結引用，某些外部標記（例如 JIRA 或 Zendesk 工單 ID）也可能會自動轉換為短連結。此設定需要管理員權限，但啟用後，即可輕鬆實現跨系統資料共用。

最後，GitHub 支援透過程式碼輸入表情符號：輸入一個冒號，後面跟著表情符號名稱，再以另一個冒號結尾。開始輸入時，會出現一個建議列表，您可以按 Tab 鍵或 Enter 鍵接受建議。在評論中加入表情符號有助於使其更具人情味，但請注意不要在正式文件中過度使用。

註腳和高級內容

GitHub 也支持 腳註 使用基於括號的語法和帶有交錯字元的識別碼。在需要引用的位置，插入類似 `<input>` 的內容，然後在文件末尾使用相同的標籤定義該註釋的文本，後面跟著冒號和內容。

腳註可以跨越多行，要在腳註內強制換行，只需在行尾使用雙空格，就像 Markdown 正文一樣。渲染時，GitHub 會在文字上方顯示上標，並在文末顯示腳註列表，其中包含用於在參考文獻和腳註之間跳轉的反向連結。

GitHub提供的另一項進階功能是… 警報 這些術語（注意、提示、重要、警告和警告）前面已經討論過。建議僅在真正必要時使用，並避免過多組合使用，以免讀者感到不知所措。這些術語不能嵌套在其他複雜元素中，因此仔細規劃其放置位置至關重要。

最後，你可以讓 GitHub 暫時隱藏已渲染的 Markdown 部分內容（例如用 HTML 註解包裹），或是忽略對某些反斜線字元的處理。這在編寫文件時尤其有用。 Markdown 自身的語法 你需要提供例子的原貌，不要加以解釋。

Reddit 上的 Markdown：Snoomark 和編輯模式

Reddit 是一個討論平台，幾乎任何主題都歡迎，並以子版塊（subreddit）的形式組織起來。在格式方面，它提供了兩種編輯器：一種用於更直觀的富文本編輯器，另一種用於基於 Markdown 的純文字編輯器。如果您想要快速編輯並精細控制最終效果，建議您使用 Markdown 編輯器。

Reddit 預設啟用富文本編輯器，因此要切換到標記語言模式，您需要點擊對應的選項。 Markdown 模式 在貼文或評論的文字方塊中，您可以直接使用 Snoomark 語法。

如果您希望始終載入 Markdown 編輯器，請前往使用者設置，進入「訂閱源設定」部分，並啟用該選項。 預設使用 Markdown 格式這樣，每次您開始撰寫帖子或評論時，Markdown 編輯器都會自動打開，而無需您手動更改。

Reddit 支援大多數基礎和高級 Markdown 功能：標題、粗體和斜體、列表、引用、程式碼區塊、鏈接，以及一些它自己的額外功能，例如劇透。然而，與 GitHub 相比，它存在明顯的不足，尤其是在以下方面： 處理圖像這很大程度上取決於上下文和編輯器的類型。

Reddit支援的語法和劇透

Reddit 使用的 Snoomark 變體與 GitHub 有許多共同之處，因此，如果您已經熟練掌握 Markdown 程式碼倉庫的使用，那麼將這些知識遷移到 Reddit 環境就非常簡單。您可以使用標題來組織長篇帖子，使用編號或項目符號列表，使用引用來回覆其他用戶，並使用程式碼區塊來顯示命令或技術程式碼片段。

其中一個顯著差異在於Reddit處理問題的方式 圖像雖然在許多情況下，圖片是透過圖形介面上傳的，而不是直接使用 Markdown 語法上傳的，但處理文字內容的引擎仍然是 Snoomark，因此這些圖片周圍的格式是基於 Markdown 的。

另一方面，Reddit 補充道 附加元素 劇透內容並非標準規範的一部分。劇透內容可讓您將文字隱藏在一個圖層後面，使用者可以透過點擊圖層來顯示該圖層。從技術上講，Reddit 在處理劇透內容時，會將其轉換為 HTML、CSS 類別和平台特定的 JavaScript 程式碼的組合。

劇透內容的 HTML 表示形式包含控制何時顯示或隱藏內容的處理程序。雖然理論上可以用純 HTML 編寫類似的功能，但在 Reddit 上，這取決於其內部實作。作為用戶，重要的是，在編寫內容時，您只需使用編輯器提供的特定劇透語法即可。 Snoomark負責翻譯。 到合適的結構。

簡而言之，Snoomark 繼承了 GitHub Flavored Markdown 的許多特性，但它更著重於滿足討論社群的需求，而不是專案文件。即便如此，其核心仍然相同：將包含簡單符號的純文字轉換為結構化且易於閱讀的內容。

在 GitHub 和 Reddit 上掌握 Markdown 語法，可以顯著提高編寫技術文件、創建條理清晰的問題、在 pull request 中留下明確的評論以及參與 Reddit 討論的效率。只要掌握一些關鍵規則——標題、強調、列表、引用、程式碼區塊、連結、圖片，以及一些技巧，例如表格、可折疊詳情、警告框、腳註和劇透——你就能從編寫純文字轉變為創建內容豐富的文件。 清晰、易於瀏覽且專業的內容 無需觸碰滑鼠的任何按鈕。