web-dev-qa-db-ja.com

github.comでREADME.mdを使用する

READMEファイルを更新するときにgithubで使用される軽量マークアップ言語にあまり詳しくありません。

オープンソースライブラリのREADME/wikiファイルに適切なマークアップ構文を作成する方法について参照できるリソースはどこにありますか？

また、更新されたREADMEをgithubリポジトリにプッシュする前に、「ブラウザーでドキュメントをローカルでレビュー」できるツールはありますか？

githubmarkdownmarkup
106
Calvin Cheng

問題のマークアップは、偶然にMarkdownと呼ばれ、 Daring Fireball blog の著者であるJohn Gruberによって作成されました。 Markdownの元のソースは Daring Fireball-Markdown にあります。

多くのMarkdown方言があり、Githubのドキュメントは Github Flavored Markdown ページにあります。

そのページからの素敵なヒント：

githubページでMarkdownエディターを使用してMを押し、チートシートを表示します。

Github Markdown Live Preview ページを使用して、Markdownドキュメントをテストすることもできます。

2012-11-08の更新：Markdown構文を標準化するための取り組みが進行中です。 マークダウンの未来-ジェフアトウッド、コーディングホラー および W3Cマークダウンコミュニティグループ を参照してください。

2014-09-09の更新： CommonMark マークダウンの標準と仕様がリリースされました。

127
Patrick Klingemann

（ この回答を再投稿 いくつかの編集を行います。）

ゲームに少し遅れましたが、Pythonで小さなCLIを作成しました。 Grip（Github Readme Instant Preview） と呼ばれます。 Patrickの答えに加えて、これにより「ドキュメントをブラウザでローカルにレビューする」ことができます。

以下でインストールします：

$ pip install grip

そして、それを使用するには、単純に：

$ grip

次に、localhost:5000にアクセスして、その場所にあるreadme.mdファイルを表示します。

独自のファイルを指定することもできます。

$ grip CHANGES.md

そして、ポートを変更します。

$ grip 8080

または、前の2つを組み合わせます。

$ grip CHANGES.md 8080

GitHub-Flavored Markdown（つまり、コメントや問題のレンダリング方法）をレンダリングすることもできます。オプションで、他の問題へのハイパーリンク参照へのレポコンテキストを使用することもできます。

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

簡潔にするために、CLIヘルプを使用して残りのオプションとその詳細を参照してください。

$ grip -h

注目すべき機能：

  • GitHubとまったく同じようにページを表示します
  • フェンス付きブロック
  • Python API
  • リンクされたファイル間を移動する
  • レンダリングされたドキュメントをファイルにエクスポートする

お役に立てれば。 チェックアウト 。

10
Joe

ここにニースのオンライン/ライブエディターがあります。

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

GitHubにはPreviewボタンもあります。

次のスクリーンショットで、README.mdで[編集]をクリックするとこのボタンが表示されることを確認してください。

enter image description here

私見ライブ エディター は、GitHubで利用可能な現在のものよりも優れています。

UPDATE

ちょうど今、MarkdownとVisual Studioを検索した後、VSを使用している場合、 Web Essentials をインストールし、Visual Studio内からMarkdownをサポートできることがわかりました。カッコいい！

次のものがあります。

  • 構文の強調表示=> Markdown構文の完全な色付け
  • 埋め込み言語用のIntelliSense（W00T）=> GitHubの埋め込み言語機能は、 `` `言語構文。

enter image description here

  • プレビューウィンドウ=>レンダリングされたHTMLのプレビューウィンドウを並べて表示する
  • HTMLにコンパイル=> Markdownファイルを右クリックし、MarkdownをHTMLにコンパイルを選択します。これにより、Markdownファイルの下にネストされた.htmlファイルが生成され、Markdownファイルが変更されても同期が維持されます。
  • カスタムスタイルシート=>ソリューション固有のスタイルシートを追加して、プレビューウィンドウのスタイルを制御できます。

それについての詳細 こちら 。

5
Leniel Maccaferri

2014年2月以降、「 Rendered Prose Diffs 」を使用すると、マークダウンファイルにレンダリングされたバージョンのdiffも表示されることに注意してください。

散文ファイルを含むコミットおよびプルリクエストには、ソースおよびレンダリングビューが追加されました。

https://f.cloud.github.com/assets/17715/1999080/7f0c15a2-853e-11e3-95dc-1d7737e1ec20.png

テキスト以外の変更は、低キーの点線の下線付きで表示されます。テキストにカーソルを合わせて、変更点を確認します。

https://f.cloud.github.com/assets/17715/2005588/714cb5ea-86ef-11e3-9e92-a0d11ba6084f.png

4
VonC

現在、ファイルを編集しながらプレビューできます。

enter image description here

1
Ruby

別のオプション-Githubの新しいテキストエディター、Atomは、編集時にgithub-flavoured markdownをレンダリングします。 https://atom.io/ を参照してください

長期的に（ビールのように）無料になるかどうかはわかりません。

1
user2428107

他のツールで十分だとは思いませんでした。

  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が使用されるため、驚くことはありません。

0
schimmy