RAKUS Developers Blog | ラクス エンジニアブログ

株式会社ラクスのエンジニアブログ

Markdownで文章を書くための 6 + 4 記法

f:id:FM_Harmony:20180220102542p:plain

はじめに

こんにちは!FM_Harmonyです。
Rakus Developers Blogでは二回目の記事投稿になります。 前回はJavaScriptについて記事の投稿をさせていただきました。
tech-blog.rakus.co.jp

今回はMarkdownについて紹介します。
私も業務連絡等で使う機会が多いのですが、ある程度使えるようになるまで時間がかかりました。 なので、この記事が今後Markdownについて学習する方の助けになれば幸いです。

目次

Markdownとは?

Markdown(マークダウン)は、文章の書き方です。デジタル文書を活用する方法として考案されました。特徴は、

  • 手軽に文章構造を明示できること
  • 簡単で、覚えやすいこと
  • 読み書きに特別なアプリを必要としないこと
  • それでいて、対応アプリを使えば快適に読み書きできること

などです。

(日本語Markdownユーザー会公式サイト、Markdownの概要より引用)

要するに、文章を見やすく手軽に書くための記法Markdownです。 見出しや表組みなどの文章の構造を設定したり、太字や囲みなど文章を装飾することが簡単にできます。

私が知っているものだと、以下のサービスで利用することができます。

  • チャットツール(Slack, Mattermost, ...)
  • プロジェクト管理サービス(GitHub, GitLab, ...)
  • Redmine*1
  • 記事投稿サービス(はてなブログ, Qiita, ...)

上の三種類はエンジニアが利用することの多いサービスですね。 これらのサービスを利用して、円滑なコミュニケーションを図るためにMarkdownへの理解は必須です。

では、Markdownの記法を紹介します。 今回紹介するのは構造に関する6個の記法と装飾に関する4個の記法、合わせて10個の記法です。

構造に関する6個の記法

改行

文章を意図的に改行する際は、改行したい部分に(半角スペース2つ)を付けて改行します。

  • 使用例(文章をドラッグしてみてください)
改行は文章の終わりで行いましょう。  
こんな風にね。
  • 実際の表示
    改行は文章の終わりで行いましょう。
    こんな風にね。

見出し

段落に見出しを付けたい場合は、#(シャープ)を利用します、#が多いほど小さな見出しになります。 文章とマークの間に半角スペース1個分の空白が必要な場合がほとんどです。
また、はてなブログやQiitaでは、見出しから自動的に目次を作成してくれます

  • 使用例
#### 見出しの例  
見出しがあると話の流れが分かり易いですね。  
##### 小見出しの例  
小見出しを入れるためには#の数を増やします。
  • 実際の表示

    見出しの例

    見出しがあると話の流れが分かり易いですね。
    小見出しの例

    小見出しを入れるためには#の数を増やします。

列挙

一つ、二つ、・・・というように何かを列挙したい場合は*(アスタリスク)、+(プラス)、 -(マイナス)のどれかを使います。 どれを使っても表示に変わりはありません。

列挙マークも見出しマークと同じで、文章とマークの間は半角スペース1個分空けます。 また、使用例のように列挙の中に文章を入れたり、階層的に列挙することも可能です。

ちなみにはてなブログでは、最初の列挙マークの上に空白行を入れないとマークとして認識されないことがあるので注意が必要です。

  • 使用例
  * りんご  
     おいしいよね!
  * みかん  
     * 温州みかん  
     * 愛媛みかん
  * もも  
  • 実際の表示
    • りんご
      おいしいよね!
    • みかん
    • もも

表組み

表組みを作るには、|(パイプ)、:(コロン)、-(ハイフン)の三つを利用します。

表の形式は一行目が列名、二行目が列の揃え、三行目以降が値という風になっています。 それぞれの文章を|で囲みますが、この時列と列との間で|重複しないようにします。

|列名|列名|
|:-:|:-:|
|値|値|
|列名||列名|
|:-:||:-:|
|値||値|

文章の揃え方は左揃え中央揃え右揃えから選ぶことができます。 デフォルトは左揃えです。
揃えを表すためには、:-を利用します。 :の位置で揃える方向を決めると覚えれば、ほぼ間違いありません。 が、中央揃えは-の両端に:を置くので気を付けてください。

また、一番左の|の前にスペースを入れると正しく認識されないことがあるので、注意が必要です。

  • 使用例
|揃えない列|左揃えの列|中央揃えの列|右揃えの列|
||:-|:-:|-:|
|リンゴ|ゴリラ|ラッパ|パセリ|
|こんな|ふうに|表が|できます|
  • 実際の表示
揃えない列 左揃えの列 中央揃えの列 右揃えの列
リンゴ ゴリラ ラッパ パセリ
こんな ふうに 表が できます

引用

引用を示す場合は文章の前に>(大なり記号)を置きます。 チャットなどで相手の発言を明示したい場合に利用するとよいでしょう。
注意点としては、引用マークの直後にある行も引用と認識される事が挙げられます。 引用が終わった後は、空白行を入れておくと間違いがないでしょう。

  • 使用例
> Aがいい? Bがいい?  
> それともCがいい?  
あるいはDがいい?

Aがいいね!
  • 実際の表示

    Aがいい? Bがいい?
    それともCがいい?
    あるいはDがいい?

    Aがいいね!

コードブロック

`(バッククォート)三つで文章を囲みます。 始めのバッククォート三つのあとに言語名*2を書くと、シンタックスハイライトが有効になります

コードブロック内では、Markdown記法が使えません。

  • 使用例
  ``` java
  public class SomeLogic{ 
    public static void someMethod(){
       System.out.println("Hello World!");
    }  
  }; 
  ``` 
  • 実際の表示
public class SomeLogic{ 
  public static void someMethod(){
     System.out.println("Hello World!");
  }  
}; 

装飾に関する4個の記法

強調

*アスタリスク)、または_(アンダーバー)で文章を囲みます。 強調マーク一つで囲むとイタリック体、二つで囲むと太字*3になる場合が多いようです。

  • 使用例
_Hello World!_  
**ここが大事です!**  
  • 実際の表示
    Hello World!
    ここが大事です!

囲み

`(バッククォート)一つで文章を囲みます。 ファイル名を示すときなどによく使います。

  • 使用例
`C:\Program Files\設定ファイル.xlsx`  
  • 実際の表示
    C:\Program Files\設定ファイル.xlsx

打消し線

~(チルダ)二つで文章を囲みます。
チャットでうっかり誤った情報を流したけど、書いたことは消さずに取り消したい*4なんて時に使います。

  • 使用例
会議は~~10時からです。~~  
11時からでした。
  • 実際の表示
    会議は10時からです。
    11時からでした。

埋め込みリンク

[](ブラケット)、()(丸かっこ)を使います。 []で文章を囲み、()でURLを囲むことで文章にリンクを埋め込むことができます。
URLを打てば自動的にリンクが張られるのですが、リンク先を分かりやすくしたいという場合にはこちらを使います。

  • 使用例
http://tech-blog.rakus.co.jp/
ラクスの技術者ブログは[ココ!](http://tech-blog.rakus.co.jp/)

おわりに

以上がMarkdownで文章を書くための基本的な記法になります。

Markdownの記法は他にもありますが、今回紹介したものが使えれば概ね問題ありません。 特に改行、列挙、強調、囲み、打消しの5つはよく使うので、これらを使えるようになるだけでもかなり見やすい文章を書くことができます。

Markdownを覚えるコツとしては、とにかく書いて表示を見ることに尽きます。 例えば、Mattermostではプレビュー機能が追加されましたし、StackEditなどMarkdownが有効なテキストエディタのサービスもあります。 これらを利用して理解を深めることが、Markdownに慣れるための一番の近道だと私は思います。

まだMarkdownを使っていない方は、この機会にMarkdownについて学習することをおススメします。
きっとMarkdownを身につけた後では、あなたの書く文章がより見やすくなっていることでしょう。

参考にしたサイト


*1:オプションからMarkdownを使えるようにできます、こちらを参考。

*2:ファイル名を書いてもよい場合もあります。

*3:はてなブログのPC版では太字の代わりに、色付き囲みになります。

*4:文章を消すと発言が追えなくなるので、消さずに内容だけ編集することが多いためです。

Copyright © RAKUS Co., Ltd. All rights reserved.