README.mdファイル。マークダウン記法まとめ

by codechord. 6 Comments

  • このエントリーをはてなブックマークに追加
  • このエントリーをはてなブックマークに追加

つい先日から、ようやくgithubを使い始めました。
gitのことはあまり勉強してないので右も左もわからず、とりあえず、公開されてるレポジトリのクローンを作りまくってニヤニヤ閲覧しています。

で、そろそろ自分もリポジトリを作りたいなと思って、作り方を調べてたんですが、
README.md」ファイルというものの存在を知りました。

拡張子「.md」?何の事かさっぱりわからず、ドットモジュールって勝手に思ってたんですけど、全然違いました。「マークダウン」の略でした///

マークダウンとは

マークダウンファイルとは何ぞや。調べました。
普通のテキストファイルを、ちょっとした法則にならって書くだけで、HTMLマークアップせずに、自動的にHTMLコードとして変換して出力してくれるというものでした。
このちょっとした法則がマークダウン記法っていう。

READMEファイルは、このマークダウン記法で書くと、わかりやすいREADMEが作れるよ。ということですが、
要は、READMEを書くときに、読む人にもわかりやすいように構成考えて書こうね。
って事だと思います。

いろんなところで使われてるみたいで、ホント今更知った。
ちなみに、githubでのマークダウン記法はGFM(GitHub Flavored Markdown)と呼ばれてるらしい。

マークダウン記法

さて、それではまとめていきます。
ざっと調べただけなので、不足や間違いがあるかもしれません。

段落

空行をあける

1段落目
(空行をはさむ)
2段落目

改行

行末に2つのスペースを入れる。

1行目  ←行末に半角スペース2つ
2行目

強調

・強調。アスタリスク(*)またはアンダーバー(_)で囲う

*強調* または _強調_

・強い強調。アスタリスク2つ(**)またはアンダーバー2つ(__)で囲う

**強い強調** または __強い強調__

コード表示(等幅フォントで表示)

・インラインのコード。バッククォーテーションで囲う

`$hoge = 1`

・複数行のコード。半角スペースを4つ行頭に

    ←半角スペース4つ $hoge1 = 1 //1行目
    ←半角スペース4つ $hoge2 = 2 //2行目
    ←半角スペース4つ $hoge3 = 3 //3行目

リスト

行頭にアスタリスク(*)か、番号ピリオド(1. )

* リスト1
* リストリスト1-2
* リスト2

1. 順番つきリスト
2. 順番つきリスト
3. 順番つきリスト

見出し

行頭の#の個数でH1~H6を表す。

# H1見出し
## H2見出し
#### H4見出し

または、

H1見出し(イコール行を挿入。)
==================

H2見出し(ハイフン行を挿入。)
---------------------------------

引用(blockquote)

メールの引用の感じ。途中で改行しても、ダブルクォーテーション内は改行されない。入れ子もOK

> "引用本文引用本文引用本文引用本文
引用本文引用本文引用本文引用本文引用本文引用本文。"

> 引用本文引用本文引用本文引用本文
> 引用本文引用本文引用本文引用本文引用本文引用本文。
> > 入れ子入れ子
> > 入れ子入れ子
> 引用本文引用本文引用本文引用本文
> * リスト
> 引用本文引用本文引用本文引用本文
> 1. 番号リスト
> 引用本文引用本文引用本文引用本文
> $hgoe = 1 コードを書いてみたり
> 引用本文引用本文引用本文引用本文

リンク

記法は3種。リンクのタイトルは省略可能。

■自動リンク
アングルブラケット< >でURLを囲う。メアドでも可能

<http://example.com>
<example@example.com>

■通常のインライン記法

[リンクのテキスト](リンクのアドレス "リンクのタイトル")

■外部参照リンク(段落の外でリンクをまとめれる)

[リンクのテキスト][linkref]

[linkref]: リンクのアドレス "リンクのタイトル"

・実際の例:

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

[google]: http://google.com/        "Google"
[yahoo]:  http://search.yahoo.com/  "Yahoo Search"
[msn]:    http://search.msn.com/    "MSN Search"

画像

先頭にビックリマーク

![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional title")

・リンクと同じように参照表記も可能
![Alt text][id]

[id]: url/to/image  "Optional title attribute"

水平線

3つ以上のハイフン、アスタリスク、アンダースコアをならべる。間にスペースをいれても良い

* * *
***
*****
- - -
---------------------------------------

その他の注意

&マークなどは「&amp;」に変換しておく。

■エスケープしておくべき箇所

  • 行頭でのピリオドをリストではなく、通常のように表示させたい場合。
  • アスタリスクを通常で表示させたい場合。
  • バッククォートを表示させたい場合は、連続バッククォート。“あいう`えお“

エスケープ一覧

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

まとめ

結局のところ、実際に、自分で書いてみないとわかりません。
こちらのページでリアルタイムで反映されるwebエディタがあるので、ちょっと触ってみるだけで、雰囲気がつかめるかと思います。

参考させていただいたサイト

githubに特化したマークダウンは本家を見るべきですね。


README.mdファイル。マークダウン記法まとめ への6件のフィードバック

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

次のHTML タグと属性が使えます: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>