markdownの記法まとめとhexoで記事を書く方法(プラグインや独自タグ定義解説あり)|おちゃカメラ。

本日限定

Amazonタイムセール開催中

セール商品を見に行く

markdownの書き方の解説や、ブログジェネレータであるHexoで使える特別な記法をまとめてみました。実際にこちらのブログもMarkdownで記事を書いています。

前半では、markdownの一般的な記述について説明を行います。見出し(h1)やテーブル(table)、リンク(link)、画像(iamge)など、代表的なものから順番に説明していきたいと思います。

後半では、ブログジェネレータであるHexoで使える独自の記法、プラグインを活用した独自タグの利用例、また独自タグの定義方法をまとめます。

また、hexoで使っているプラグインや使い方については、別途こちらをご覧ください。

自身のブログ
Hexoブログで使ってるプラグインを晒してみる
 連載：Hexoの使い方とブログの初め方

それでは早速みていきましょう！

markdownの記法一覧

まずはmarkdownの一般的な記述方法をまとめてみたいと思います。こちらはHexoでも使用できます。

h2〜h6 見出し

見出しをmarkdownで記述するには、行の始めに#を付けて、見出しの文字列と半角スペースで区切ります。#の数に応じて<h2></h2>から<h6></h6>まで生成できます。

sample-h.md

## h2の見出し
### h3の見出し
#### h4の見出し
##### h5の見出し
###### h6の見出し

生成されるHTMLタグは以下のようになります。

sample-h.html

<h2>h2の見出し</h2>
<h3>h3の見出し</h3>
<h4>h4の見出し</h4>
<h5>h5の見出し</h5>
<h6>h6の見出し</h6>

H4見出しの例

↑こちらはH4の見出しを表示したサンプルです。

H5見出しの例

↑こちらはH5の見出しを表示したサンプルです。

H6見出しの例

↑こちらはH6の見出しを表示したサンプルです。

a リンク

リンクを記述するには[リンクを貼りたい文字列](URL "URL先のタイトル")と記述します。URLは相対パスや絶対パスの指定ができます。

sample-a.md

1 2	[Yahooのサイト](https://www.yahoo.co.jp/ "ヤフー") [ブログ内のリンク](/tags/hexo-npm-nodejs/ "node.jsに関する記事")

上記のように記述すると、以下のように表示されます。

Yahooのサイト
 ブログ内のリンク

生成されるHTMLタグは以下のようになります。

sample-a.html

1
2

<a href="https://www.yahoo.co.jp/" title="ヤフー" target="_blank" rel="external">Yahooのサイト</a>
<a href="/tags/hexo-npm-nodejs/" title="node.jsに関する記事">ブログ内のリンク</a>

img 画像の埋め込み

画像を埋め込むには![画像の代替文字](画像のURL "画像のタイトル")と記述します。widthやheightを指定した場合はHTMLタグの直接記述が必要になります。

sample-img.md

1	![カメラの画像](https://farm8.staticflickr.com/7558/camera.jpg "カメラの画像を貼りました")

上記のように記述すると、以下のように表示されます。

iphone5 | 写真 2014-10-19 13 58 11 BESSA R2

生成されるHTMLタグは以下のようになります。

sample-img.html

1	<img src="https://farm8.staticflickr.com/7558/camera.jpg" alt="カメラの画像" title="カメラの画像を貼りました"></p>

table テーブル

テーブルは以下のように、|で囲みます。左寄せや右寄せ、中央揃いは行の区切りに:を用いて表します。:の位置によって寄せ方が変わります。

sample-table.md

| 左寄せ      |        右寄せ |     中央      |
|:-----------|------------:|:------------:|
| This       |        This |     This     |
| column     |      column |    column    |
| will       |        will |     will     |
| be         |          be |      be      |
| left       |       right |    center    |
| aligned    |     aligned |   aligned    |

上記のようにmarkdownを記述すると、以下のように表示されます。

左寄せ	右寄せ	中央
This	This	This
column	column	column
will	will	will
be	be	be
left	right	center
aligned	aligned	aligned

生成されるHTMLタグは以下のようになります。

sample-table.html

<table>
    <thead>
        <tr>
            <th style="text-align:left">左寄せ</th>
            <th style="text-align:right">右寄せ</th>
            <th style="text-align:center">中央</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td style="text-align:left">This</td>
            <td style="text-align:right">This</td>
            <td style="text-align:center">This</td>
        </tr>
        <tr>
            <td style="text-align:left">column</td>
            <td style="text-align:right">column</td>
            <td style="text-align:center">column</td>
        </tr>
        <tr>
            <td style="text-align:left">will</td>
            <td style="text-align:right">will</td>
            <td style="text-align:center">will</td>
        </tr>
        <tr>
            <td style="text-align:left">be</td>
            <td style="text-align:right">be</td>
            <td style="text-align:center">be</td>
        </tr>
        <tr>
            <td style="text-align:left">left</td>
            <td style="text-align:right">right</td>
            <td style="text-align:center">center</td>
        </tr>
        <tr>
            <td style="text-align:left">aligned</td>
            <td style="text-align:right">aligned</td>
            <td style="text-align:center">aligned</td>
        </tr>
    </tbody>
</table>

ul、ol リスト表記

リスト表記は-と半角スペースを先頭に記述していきます。番号付きリスト表記は1.と半角スペースを先頭に記述していきます。またリストの説明を入れたい場合には先頭に半角スペース4つを追加し、前後を空行で挟みます。

sample-list.md

- hoge
- fuga
- foo

    リストの説明(先頭に半角スペース4つを追加し、前後を空行で挟む)

- bar


1. hoge
2. fuga
3. foo
3. bar

便利なことに、番号付きリストの表記では番号が連続していなくてもmarkdownレンダラーの方で上手いこと書き換えてくれます。上記のようにmarkdownを記述すると、以下のように表示されます。

hoge
fuga
foo

リストの説明(先頭に半角スペース4つを追加し、前後を空行で挟む)
bar

hoge
fuga
foo
bar

生成されるHTMLタグは以下のようになります。

sample-list.html

<ul>
  <li>hoge</li>
  <li>fuga</li>
  <li><p>foo</p>
    <p>リストの説明(先頭に半角スペース4つを追加し、前後を空行で挟む)</p>
  </li>
  <li><p>bar</p></li>
</ul>

<ol>
  <li>hoge</li>
  <li>fuga</li>
  <li>foo</li>
  <li>bar</li>
</ol>

リストはネストも可能です。

sample-list.md

1. hoge
2. fuga

    1. hoge
    2. fuga
    
        リストのネストが可能です。
    
    3. foo
    4. bar

3. foo
3. bar

次のように表示されます。

hoge
fuga
1. hoge
2. fuga
  
  リストのネストが可能です。
3. foo
4. bar
foo
bar

em、strong 強調

強調を表すには*で囲みます。

sample-em.md

1 2	em strong

上記のようにmarkdownを記述すると、以下のように表示されます。

em
strong

sample-em.html

1 2	<em>em</em> <strong>strong</strong>

code block コード・ブロック

コード・ブロック(本文とは切り離した複数行のプログラムコード)は｀3つで囲み、言語名を記述します。テーマやエンジンがサポートしている言語によってはシンタックスハイライトしてくれます。

sample-codeBlock.md

｀｀｀javascript
// 本文とは切り離した場所に複数行のプログラムコードを表示させます
console.log("hoge");
｀｀｀

上記のようにmarkdownを記述すると、以下のように表示されます。

1 2	// 本文とは切り離した場所に複数行のプログラムコードを表示させます console.log("Hoge");

inline code インライン・コード

インライン(本文中にプログラム・コードを含める)でコードを記述するには｀1つで囲みます。

sample-inlineCode.md

1	本文中にコードを表示するには｀console.log("hoge");｀と記述します

上記のようにmarkdownを記述すると、以下のように表示されます。

本文中にコードを表示するにはconsole.log("hoge");と記述します

del 打ち消し

打ち消しを表すには~2つで囲みます。

sample-del.md

1	~~打ち消したい文字~~

上記のようにmarkdownを記述すると、以下のように表示されます。

~~打ち消したい文字~~

生成されるHTMLタグは以下のようになります。

sample-del.html

1	<del>打ち消したい文字</del>

kbd キーボード

キーボードはmarkdownではサポートされていないため、タグを直接記述する必要があるようです。markdownはhtmlが混在していてもそのまま表示してくれます。

sample-keyBoard.md

1	キーボードは<kbd>Alt</kbd>のように記述します

上記のようにhtmlを記述すると、以下のように表示されます。

キーボードはAltのように記述します

blockquote 引用

引用を表すには>と半角スペースを先頭に記述していきます。また引用のネストも可能です。

sample-blockquote.md

> 引用
> > 引用のネスト

サイトの引用
> Yahoo(サイト名)
> <cite>Yahoo! - <a href="https://yahoo.co.jp" title="">yahoo</a> </cite>

上記のようにmarkdownを記述すると、以下のように表示されます。

引用

引用のネスト

サイトの引用

Yahoo(サイト名)
Yahoo! - yahoo

hexoで使える独自タグ

次に、静的ファイルジェネレータのhexoで独自に定義された便利なタグや、プラグインから利用できるタグをご紹介したいと思います。

excerpt 記事の抜粋や概要

hexoから標準で使えるタグです。記事のmarkdown中にを記述すると、それ以前の文章が概要扱いとなり、read moreをサポートしているhexoテーマなどで概要表示ができます。また検索エンジンの結果で表示されるmeta descriptionにも使われる場合があります。

sample-excerpt.md

1
2
3

moreの直前に記述した文字列は概要として扱われます。
<!-- more -->
これ以降は記事の本文として扱われ、read moreをサポートしているテーマでは続きとして表示される内容となります。

toc 目次の自動生成

こちらもhexoで使えるタグです。tocとはthe table of contentsの略で、意味は目次です。hexo-tocというプラグインをインストールすると使えるようになります。

bash

1	$ npm install hexo-toc --save

markdownで記述した文中のh2〜h6タグを収集し、目次をリスト表記で生成してくれます。こちらの記事でも前半で目次を貼り付けていますので、表示例は当記事の前半にてご確認ください。

sample-toc.md

1 2	この直下に目次が生成されます。 <!-- toc -->

youtubeやvimeoの埋め込み

こちらもhexoから標準で使えるタグです。markdownに動画を埋め込むには、https://www.youtube.com/watch?v=の後ろに続く動画のID動画を記述していきます。

sample-movie.md

{% youtube VtL0LAHLEY4 %}
上記のようにしてyoutubeの動画を埋め込みます。VtL0LAHLEY4はURLに含まれる動画のIDです。
{% vimeo 27246366 %}
上記のようにしてVimeoの動画を埋め込みます。27246366はURLに含まれる動画のIDです。

上記のようにmarkdownを記述すると、以下のように表示されます。動画の埋め込みの表示例はこちら。

youtubeの動画を埋め込む。

引用元のyoutube動画：https://www.youtube.com/watch?v=VtL0LAHLEY4

vimeoの動画を埋め込む。

引用元のvimeo動画：https://vimeo.com/27246366

flickrの画像を埋め込む

こちらはプラグインのhexo-tag-flickrをインストールすると使えるタグです。flickrのPhoto IDを指定するだけで、簡単に画像を埋め込むことができます。インストールはnpmから可能です。

bash

1	$ npm install hexo-tag-flickr --save

hexo-tag-flickr
github - hexo-tag-flickr

markdownには以下のように記述します。photoは生成されるimgタグに指定したいクラス名(複数指定可)、b(=長辺1024px)は表示される画像のサイズの指定です。

sample-flickr.md

1 2	{% flickr photo 24286149303 b %} 上記のようにしてflickrの画像を表示させます。24286149303はflickrのURLに含まれるphoto IDです。

上記のようにmarkdownを記述すると、以下のように表示されます。flickr画像の埋め込み例はこちら。

The phantom | α7RII + FE 70-200mm F4 OSS

instagramを埋め込む

こちらもプラグインによって埋め込み可能です。hexo-tag-instagramをインストールすると、短い記述で埋め込みができます。

bash

1	$ npm install hexo-tag-instagram --save

hexo-tag-instagram
github - hexo-tag-instagram

sample-instagram.md

1
2

{% instagram https://www.instagram.com/p/3yNx8hE6iE/ %}
上記のようにしてインスタグラムのポストをブログに表示させます。3yNx8hE6iEはポストのURLに含まれるIDです。

上記のように記述するとインスタグラムの投稿記事をブログに表示させる事ができます。

引用元のポスト：https://www.instagram.com/p/3yNx8hE6iE/

twitterツイートを埋め込む

こちらもプラグインによって埋め込み可能です。hexo-tag-twitterをインストールすると、短い記述で埋め込みができます。

bash

1	$ npm install hexo-tag-twitter --save

hexo-tag-twitter
github - hexo-tag-twitter

simple-twitter.md

1	{% twitter https://twitter.com/tea0828/status/819885806714138624 %}

上記のように記述すると、以下のように表示されます。

引用元のツイート：https://twitter.com/tea0828/status/819885806714138624

Sound Cloudのトラックを埋め込む

こちらもプラグインによって埋め込みが可能です。hexo-tag-soundcloudをインストールすると、短い記述で埋め込みができるようになります。

bash

1	$ npm install hexo-tag-twitter --save

hexo-tag-soundcloud
github - hexo-tag-soundcloud

simple-soundcloud.md

1	{% soundcloud https://soundcloud.com/officialmedasin/daydream-ft-joba-1 %}

上記のように記述すると、以下のように表示されます。

引用元のページ：https://soundcloud.com/officialmedasin/daydream-ft-joba-1

google mapを埋め込む

こちらもプラグインによって埋め込み可能です。hexo-tag-googlemapsをインストールすると、緯度と経度を指定するだけでgoogle mapが埋め込まれる便利なタグです。

bash

1	$ npm install hexo-tag-googlemaps --save

hexo-tag-googlemaps
github - hexo-tag-googlemaps

markdownには以下のように記述します。以下の15は地図のズーム倍率です。100%は表示される幅、250pxは高さとなります。

sample-googleMap.md

{% googlemaps 35.3129923 138.5873496 15 100% 250px %}
  白糸の滝, 35.3129923, 138.5873496
{% endgooglemaps %}
上記のように記述してgoogle mapを表示させます。35.3129923は緯度、138.5873496は経度、15はズーム倍率

google mapの地図の埋め込み例はこちら

白糸の滝の地図をブラウザまたはアプリで開く

画像の比較(jQuery TwentyTwenty)

画像でビフォー・アフターをスライド表示させます。hexo-tag-twentytwentyを使うと、簡単な記述で比較画像を表示させることができるようになります。

bash

1	$ npm install hexo-tag-twentytwenty --save

記述方法は、markdownに、以下のtwtwタグを記述するだけでOKです。before.jpgはビフォーの画像。after.jpgはアフターの画像になります。

simple-before-after.md

1	{% twtw before.jpg after.jpg %}

上記のように記述すると、以下のように表示されます。

応用編！hexoで独自に定義したタグを使う

hexoでは通常のmarkdown記述が利用できる上に、前述したような便利な独自タグをプラグインから利用できるようになっています。しかし、これでも不十分である場合には独自にプラグイン開発するか、themes/your-theme/scripts下でタグを定義することもできます。詳しくはhexo.extend.tag.registerについて解説されてるオフィシャルサイトのドキュメントをご覧ください。

hexo
hexo - tag

実装例1：Instagramの投稿記事を埋め込むHexo markdownタグ

独自定義するタグの実装例をいくつか挙げたいと思います。まずは、先程も例を挙げたインスタグラムの投稿記事を埋め込むプラグインを見ていきたいと思います。前述と同じ説明になりますが、下記のコードは｛% instagram ショートコード %｝タグを記述して、簡単にインスタグラムの埋め込みHTMLを生成させるものです。

sample-insta.md

1 2	{% instagram 8ppwIyE6lU %} 上記のようにしてinstagramの投稿記事を埋め込みます。「8ppwIyE6lU」は記事URLに含まれるショートコードです。

上記のようにmarkdownを記述すると、以下のように表示されます。

引用元のinstagram記事：https://www.instagram.com/p/8ppwIyE6lU/

上記のタグが機能するように、themes/your-theme/scripts/extend.jsで以下のように定義しました。コードの処理内容を説明すると、タグに渡される記事のショートコードを元に、Instagramの埋め込みHTMLを返します。メリットとしては、以下のコードを最新の内容にメンテナンスすることで、全ての記事対して最新の埋め込みコードが適用できる点です。

extend.js

hexo.extend.tag.register('instagram', function(args, content){

  // markdown内で {% instagram xxx %} と記述されている部分からxxxの箇所を取得する。(xxxは引数argの要素0番目)
  var postId  = args[0];
  
  // instagramの埋め込みHTML。現時点ではバージョン7を利用している
  var returnHTML = '<blockquote class="instagram-media" data-instgrm-version="7" style=" background:#FFF; border:0; border-radius:3px; box-shadow:0 0 1px 0 rgba(0,0,0,0.5),0 1px 10px 0 rgba(0,0,0,0.15); margin: 1px auto; max-width:658px; padding:0; width:99.375%; width:-webkit-calc(100% - 2px); width:calc(100% - 2px);"><div style="padding:8px;"> <div style=" background:#F8F8F8; line-height:0; margin-top:40px; padding:50.0% 0; text-align:center; width:100%;"> <div style=" background:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAsCAMAAAApWqozAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAMUExURczMzPf399fX1+bm5mzY9AMAAADiSURBVDjLvZXbEsMgCES5/P8/t9FuRVCRmU73JWlzosgSIIZURCjo/ad+EQJJB4Hv8BFt+IDpQoCx1wjOSBFhh2XssxEIYn3ulI/6MNReE07UIWJEv8UEOWDS88LY97kqyTliJKKtuYBbruAyVh5wOHiXmpi5we58Ek028czwyuQdLKPG1Bkb4NnM+VeAnfHqn1k4+GPT6uGQcvu2h2OVuIf/gWUFyy8OWEpdyZSa3aVCqpVoVvzZZ2VTnn2wU8qzVjDDetO90GSy9mVLqtgYSy231MxrY6I2gGqjrTY0L8fxCxfCBbhWrsYYAAAAAElFTkSuQmCC); display:block; height:44px; margin:0 auto -44px; position:relative; top:-22px; width:44px;"></div></div><p style=" color:#c9c8cd; font-family:Arial,sans-serif; font-size:14px; line-height:17px; margin-bottom:0; margin-top:8px; overflow:hidden; padding:8px 0 7px; text-align:center; text-overflow:ellipsis; white-space:nowrap;"><a href="https://www.instagram.com/p/' + postId + '/" style=" color:#c9c8cd; font-family:Arial,sans-serif; font-size:14px; font-style:normal; font-weight:normal; line-height:17px; text-decoration:none;" target="_blank"></a></p></div></blockquote><script async defer src="//platform.instagram.com/en_US/embeds.js"></script>';

  // 生成したhtmlをタグの出力結果として返す
  return returnHTML;
},{
  async: true,
  ends: false
});

こちらはプラグインとして、実際にnpmに公開していますのでインストールして使うこともできます。

実装例2：注意書き欄のHTMLを生成するHexo markdownタグ

続いて、もう一つ実装例をご紹介したいと思います。Hexoの記事でBootstrapのAlertsみたいな注意書き欄を簡単に表示させたいなと思いました。そこで当ブログでは、注意書きの欄をmarkdownから簡単に生成できるように、hexo.extend.tag.registerで独自タグを拡張定義しています。markdownの記述例は以下のような形です。

sample-att.md

1
2
3

{% tag_round att 注意書きのサンプルタイトル %}
タグの中で注意書きの本文を記述します。タグの内部でも`markdown`の記法が使えます。
{% endtag_round %}

上記のようにmarkdownを記述すると、以下のように表示されます。

注意書きのサンプルタイトル

タグの中で注意書きの本文を記述します。こちらの中でもmarkdownの記法が使えます。

上記のタグが機能するように、themes/your-theme/scripts/extend.jsで以下のように定義しました。ここで一つ注意点ですが、通常タグで囲ったテキストは関数に渡される文字列として扱われるので、markdownとしてHTMLにレンダリングされません。そこで、hexoのmarkdownレンダラにも使用しているmarkedを使ってrequireしてHTMLにレンダリングさせます。

extend.js

var mk = require('marked');
hexo.extend.tag.register('tag_round', function(args, content){
  
  // 引数の取得
  var labelType  = args[0];
  var title = "";
  var i     = 0;
  
  //引数2つ目以降を文字列として結合
  for(i = 1; i < args.length; i++){
    title += ( i!=1 ? " " : "" ) + args[i];
  }
  
  // markdownの記述をHTMLにレンダリングして、改行を除去する。
  var mkdHtml = mk(content).replace(/\n/g,"");
  
  // replace escapeTAG tag
  var escapeTAGEscArr = [];
  var escapeTAGMatch  = mkdHtml.match(/\<(ol|ul|h6).*?\<\/(ol|ul|h6)\>/g);
  var innerReplace    = "";
  if(escapeTAGMatch){
    for( i = 0; i < escapeTAGMatch.length; i++){
      mkdHtml      = mkdHtml.replace(escapeTAGMatch[i],"<!--escapeTAG"+i+"-->");
      innerReplace = escapeTAGMatch[i];
      innerReplace = innerReplace.replace(/\<h6\s/g,'<h6 class="label" ');
      escapeTAGEscArr.push(innerReplace);
    }
  }

  //replace p tag
  mkdHtml = mkdHtml.replace(/\<p\>/g,'<p class="label">');
  
  // replace escapeTAG return
  escapeTAGMatch = mkdHtml.match(/\<\!\-\-escapeTAG[0-9]+\-\-\>/g);
  if(escapeTAGMatch){
    for(i=0; i<escapeTAGMatch.length; i++){
      var escapeTAGID = escapeTAGMatch[i].match(/[0-9]+/);
      mkdHtml = mkdHtml.replace( escapeTAGMatch[i] , escapeTAGEscArr[Number(escapeTAGID[0])] );
    }
  }
  
  //引数1つ目の値に応じて クラス名やアイコンを変える。
  var dClass = "attention";
  var iconClass = "exclamation-circle-icon";
  if(labelType == "att"){
    // 注意書き
    dClass = "attention";
    iconClass = "exclamation-circle-icon";
  }else if(labelType == "memo"){
  	//メモ
    dClass = "r-memo";
    iconClass = "file-text-o-icon";
  }else if(labelType == "dl"){
  	//ダウンロード
    dClass = "r-download";
    iconClass = "download-icon";
  }
  
  return '<div class="'+ dClass +'"><h5 class="label"><span class="sns-icon '+ iconClass +'"></span>' + title + '</h5>'+ mkdHtml +'</div>';
},{
  async: true,
  ends: true
});

(備録)markdownのエディタとWebツール

markdownのエディタはSublime text 3を使っています。またWebページ上でmarkdownの結果をすぐに確認したい時にはRemarkableやDillingerを使っています。Remarkableは２つの画面で構成されていて、左側にmarkdownを記述していくと瞬時にHTMLへ変換してくれる大変便利なサービスとなっています。Dillingerも同様のサービスです。