在github.com上使用README.md

Question

我不太熟悉github在更新README文件時使用的輕量級標記語言。

哪裏可以找到關於如何爲我的開源庫的README/wiki文件編寫適當的標記語法的資源？

在將更新的README推送到我的github存儲庫之前，是否有一種工具可以「在瀏覽器中本地查看我的文檔」？

Answer 1

有問題的標記巧合地叫做Markdown，由John Gruber創作，Daring Fireball blog的作者。 Markdown的原始來源可在Daring Fireball - Markdown找到。

有許多Markdown方言，Github的文檔可以在Github Flavored Markdown頁面找到。

不錯尖從該頁面：

按用降價編輯器顯示的cheatsheet任何Github的頁面上中號。

您也可以使用Github Markdown Live Preview頁面測試您的Markdown文檔。

更新2012-11-08：正在努力標準化Markdown語法。見The Future of Markdown - Jeff Atwood, Coding Horror和W3C Markdown Community Group。

更新2014-09-09：CommonMark降價標準和規格已發佈。

Answer 2

注意，由於2014年2月，以「Rendered Prose Diffs」，你還可以看到一個降價文件中的DIFF的渲染過的版本：

提交和拉請求包括散文文件現在擁有源和渲染視圖。

非文本的變化出現一個低調的虛線下劃線。將鼠標懸停在文字上可以看到發生了什麼變化：

Answer 3

我沒有發現其他工具不夠好 - 我想：

1. 能夠離線編輯
2. 不只是普通的降價，而是實際的Github風味降價

這是我最終定居在：https://github.com/ypocat/gfms

> gfms 

Github Flavored Markdown Server. 
Run in your project's root directory. 
Usage: gfms 

Options: 
    -p, --port    Port number to listen at.  [required] 
    -h, --host    Host address to bind to.   [default: "localhost"] 
    --proxy     if behind a proxy, proxy url. 
    -a, --api    Render using Github API. 
    -n, --no-api-on-reload Disable usage of Github API when the doc is manually reloaded. 

所以我別名：使用

alias gm='gfms -a -p 8070' 

的-p選項打Github的API和使用實際的，當前Github上CSS所以AREN沒有任何意外。

Answer 4

另一種選擇 - Github的新文本編輯器Atom將在您編輯時呈現Github風格的降價。請參閱https://atom.io/

我不確定它是否會免費（如啤酒）長期使用。

Answer 5

有一個很好的網上/現場編輯在這裏：

http://jbt.github.io/markdown-editor/

還有在GitHub上一個Preview按鈕。

請參閱以下屏幕截圖，當點擊編輯README.md時出現此按鈕。

恕我直言現場editor比在GitHub上可用的電流更好。

UPDATE

剛纔我尋找Markdown和Visual Studio，如果你使用VS，你可以安裝Web Essentials，並有從Visual Studio中右Markdown支持後發現的。這很酷！

它具有：

• 語法高亮=> 的降價語法
• 智能感知嵌入式語言（W00T）=>全綵色 GitHub的嵌入式語言的特點是完全支持支持語言語法。

• 預覽窗口=> 見渲染HTML
• 編譯的並排側預覽窗口中的HTML => 右鍵單擊任何降價文件，並選擇編譯降價到HTML。這將生成一個嵌套在Markdown文件下的.html文件，並且在Markdown文件更改時它將保持同步。
• 自定義樣式表=> 您可以添加特定於解決方案的樣式表來控制預覽窗口的樣式。

詳細瞭解它here。

Answer 6

（Re-posting this answer一些編輯。）

有點晚了比賽，但我在Python寫了一個小CLI。它被稱爲Grip (Github Readme Instant Preview)。再加上帕特里克的答案，這會讓你「在瀏覽器中本地查看我的文檔」。

與安裝：

$ pip install grip 

，並使用它，簡單地說：

$ grip 

接着參觀localhost:5000查看readme.md文件在該位置。

您還可以指定自己的文件：

$ grip CHANGES.md 

並更改端口：

$ grip 8080 

或合併前兩個：

$ grip CHANGES.md 8080 

，你甚至可以使GitHub- Flavored Markdown（即評論和問題是如何呈現的），可選地使用repo上下文來自動超鏈接引用NCES其他問題：

$ grip --gfm --context=username/repo issue.md 

爲了簡潔，看到的選項和他們的詳細資料，其餘使用CLI幫助：

$ grip -h 

顯着特點：

• 渲染頁面恰好出現像在GitHub上
• 圍欄塊
• 的Python API
• 導航

之間鏈接的文件

出口呈現的文檔文件希望這有助於。 Check it out。

Answer 7

到今天爲止，你可以預覽，你編輯的文件。