文章的編寫與發布（簡易方法）
這篇文章要告訴你的是：如何撰寫文章，並且上傳至 nvdoc 文件庫。
作者：蔡煥麟
前言
撰寫文章並發布至 nvdoc 網站的方法有兩種：
- 方法一：透過 GitHub 網站的 Pull Request 機制來提交變更。此方法由於牽涉儲存庫的合併請求流程，會需要事先了解 git 的相關操作。
- 方法二：在「草稿儲存庫」中編寫文章，並由相關人員校稿。待校稿完成後，通知 nvdoc 管理員，並由管理員來執行 Pull Request 流程與檔案的合併操作。此方法的程序比第一種方法簡單一些，但缺點是無法在 nvdoc 專案中自動累計文章作者與其校稿人員的貢獻度。
兩種方法各有優缺點，本文介紹的是第二種，也就是比較簡易的做法。此方法的缺點是參與寫作和校稿的人員，其貢獻度不會統計在 nvdoc 儲存庫，而只會存在 draft 儲存庫。如果你想要試試 GitHub 多人協作的標準做法，可參考另一篇文章：使用 GitHub Pull Request 流程來發布文章。
準備工作
你必須有一個 GitHub 使用者帳號，而且這個帳號必須有寫入文件庫的權限。在貢獻你的創作之前，請寫一封信給管理員，告知你想要直接上傳檔案的權限，以及你的 GitHub 帳號。待管理員加入權限之後，便可進行後續的文件編寫與上傳操作。
此外，你還需要懂 Markdown 語法，才能撰寫符合本站格式的文章。
步驟一：撰寫文章
首先，用文字編輯器寫好一篇文章，內容格式必須以 Markdown 編寫，文章頂端必須包含一個檔頭區塊（front matter）。檔頭區塊的開始標記與結束標記都是連續三個半形減號（即 dash 符號），參考以下範例：
---
title: "你的文章標題"
tags:
- 這篇文章的標籤
---
檔頭區塊裡面可以加入一些用來描述這篇文章的屬性。每次撰寫新文章的時候，可以把上面的文字區塊複製到你的文章的頂端，再修改各個屬性的內容。上面的範例有兩個屬性：
title：文章標題，請以雙引號來包住你的文章標題。tags：標籤，也就是文章內容所牽涉的議題。一篇文章可以有多個標籤，每一個標籤寫成單獨一行。
每一篇文章都應該加入適當的標籤，以便日後尋找相同議題的文章。比如說，如果你的文章內容是關於微軟 Excel 的使用技巧，就可以加入 “Excel” 標籤，那麼其他人在閱讀文章的時候，只要點擊 “Excel” 標籤，網站就會列出所有使用 Excel 標籤的文章。
範例：
---
title: "G-mail 常用快速鍵"
tags:
- gmail
- 按鍵小抄
---
上述文章範例的標題是「G-mail 常用快速鍵」，而標籤有兩個：「gmail」和「按鍵小抄」。
接在文章檔頭區塊底下的，就是文章的內文。你可以在自己創作的文件中標示作者姓名，亦可加註授權聲明，但授權方式必須與此文件庫的授權一致。
內文如果需要加入子標題，請使用兩個升記號來作為第一層標題的開頭，也就是 ##。第二層子標題則用 ###，依此類推。一篇文章裡面的標題層次最好不要超過三層。
範例：
作者：麥克阿瑟
## Gmail 簡介
Gmail 是 Google 提供的電子郵件服務。
## 常用快速鍵
下表是常用的 Gmail 快速鍵……
文章寫好之後，請遵照此格式來替檔案命名：「yyyy-mm-dd-文章標題.md」。其中 yyyy 是四位數的西元年，mm 是兩位數的當前月份，dd 則是兩位數的日期。文章標題就是你打算撰寫的文章標題，中英文皆可，但請不要有空白字元。檔名中的文章標題如果需要隔開字詞，請一律使用減號，而不要使用空白字元。底下是兩個檔案名稱的範例：
- 2022-03-27-Windows-常用快速鍵.md
- 2022-03-27-Windows-shortcut-keys.md
檔名中的文章標題會成為日後發布於網站上的文章網址的一部份，所以如果能夠使用英文是最好的。中文網址雖然能夠正常運作，但是在轉貼連結的時候，網址當中的中文字元往往會經過編碼，不利閱讀。
值得一提的是，如果你在發布文章後的某一天修改了文章內容，網站依然會以此文章的檔案名稱中的日期來做為文章的最後更新日期。如果你希望文章更新之後，可以出現在網頁排序結果的頂端，則可以在此文章的檔頭區塊加入 date 屬性來明確指出此文章的最後更新時間。日期格式也是 yyyy-mm-dd。範例如下：
---
title: "G-mail 常用快速鍵"
date: 2022-03-25
tags:
- gmail
---
步驟二：上傳文章
如果你已經有 GitHub 帳號，而且已經有寫入此文件庫的權限，便可依下列步驟來上傳你的文章：
- 用瀏覽器開啟網址：https://github.com/visualaids/draft/upload/main，這是上傳檔案的頁面。
- 在此頁面中找到 choose your files 按鈕，點此按鈕即可上傳你的文章檔案。
- 在此頁面下方的 Commit changes 欄位中輸入簡短的文字描述，以說明這次上傳的內容。你也可以不加入說明文字，採用 GitHub 網頁預設提供的文字，然後移往頁面下方的 Commit changes 按鈕，點此按鈕即可將你挑選的檔案上傳。
檔案上傳後，如果需要其他人校稿，請自行聯繫校稿人員，並告知文章草稿儲存庫的網址：https://github.com/visualaids/draft。只要對方的 GitHub 帳號有寫入儲存庫的權限，便可在 GitHub 網站上直接修改文章內容。
校稿工作完成後，欲發布文章時，請通知 nvdoc 管理員。等到管理員執行了後續的檔案合併工作，你的文章才會出現在 nvdoc 網站上。
結語
本文介紹的作法，是透過 GitHub 網頁的檔案上傳功能來將你的文章保存至遠端 GitHub 主機。如果你想要使用 Git 指令，並學習多人協作的版本控制流程，則可以參考另一篇文章的作法：使用 GitHub Pull Request 流程來發布文章。
留言