markdownの書き方の解説や、ブログジェネレータであるHexoで使える特別な記法をまとめてみました。実際にこちらのブログもMarkdownで記事を書いています。
前半では、markdownの一般的な記述について説明を行います。見出し(h1)やテーブル(table)、リンク(link)、画像(iamge)など、代表的なものから順番に説明していきたいと思います。
後半では、ブログジェネレータであるHexoで使える独自の記法、プラグインを活用した独自タグの利用例、また独自タグの定義方法をまとめます。
また、hexoで使っているプラグインや使い方については、別途こちらをご覧ください。
それでは早速みていきましょう!
目次
photo by Mr. Alex Garcia - Double Cliche on flickr
markdownの記法 一覧
まずはmarkdownの一般的な記述方法をまとめてみたいと思います。こちらはHexoでも使用できます。
h2〜h6 見出し
見出しをmarkdownで記述するには、行の始めに#
を付けて、見出しの文字列と半角スペースで区切ります。#
の数に応じて<h2></h2>
から<h6></h6>
まで生成できます。
1 | ## h2の見出し |
生成されるHTMLタグは以下のようになります。
1 | <h2>h2の見出し</h2> |
a リンク
リンクを記述するには[リンクを貼りたい文字列](URL "URL先のタイトル")
と記述します。URLは相対パスや絶対パスの指定ができます。
1 | [Yahooのサイト](http://www.yahoo.co.jp/ "ヤフー") |
上記のように記述すると、以下のように表示されます。
生成されるHTMLタグは以下のようになります。
1 | <a href="http://www.yahoo.co.jp/" title="ヤフー" target="_blank" rel="external">Yahooのサイト</a> |
img 画像の埋め込み
画像を埋め込むには![画像の代替文字](画像のURL "画像のタイトル")
と記述します。widthやheightを指定した場合はHTMLタグの直接記述が必要になります。
1 | ![カメラの画像](https://farm8.staticflickr.com/7558/camera.jpg "カメラの画像を貼りました") |
上記のように記述すると、以下のように表示されます。
生成されるHTMLタグは以下のようになります。
1 | <img src="https://farm8.staticflickr.com/7558/camera.jpg" alt="カメラの画像" title="カメラの画像を貼りました"></p> |
table テーブル
テーブルは以下のように、|
で囲みます。左寄せや右寄せ、中央揃いは行の区切りに:
を用いて表します。:
の位置によって寄せ方が変わります。
1 | | 左寄せ | 右寄せ | 中央 | |
上記のようにmarkdownを記述すると、以下のように表示されます。
左寄せ | 右寄せ | 中央 |
---|---|---|
This | This | This |
column | column | column |
will | will | will |
be | be | be |
left | right | center |
aligned | aligned | aligned |
生成されるHTMLタグは以下のようになります。
1 | <table> |
ul、ol リスト表記
リスト表記は-
と半角スペースを先頭に記述していきます。番号付きリスト表記は1.
と半角スペースを先頭に記述していきます。またリストの説明を入れたい場合には先頭に半角スペース4つを追加し、前後を空行で挟みます。
1 | - hoge |
便利なことに、番号付きリストの表記では番号が連続していなくてもmarkdownレンダラーの方で上手いこと書き換えてくれます。上記のようにmarkdownを記述すると、以下のように表示されます。
- hoge
- fuga
foo
リストの説明(先頭に半角スペース4つを追加し、前後を空行で挟む)
bar
- hoge
- fuga
- foo
- bar
生成されるHTMLタグは以下のようになります。
1 | <ul> |
em、strong 強調
強調を表すには*
で囲みます。
1 | *em* |
上記のようにmarkdownを記述すると、以下のように表示されます。
em
strong
1 | <em>em</em> |
code block コード・ブロック
コード・ブロック(本文とは切り離した複数行のプログラムコード)は`
3つで囲み、言語名を記述します。テーマやエンジンがサポートしている言語によってはシンタックスハイライトしてくれます。
1 | ```javascript |
上記のようにmarkdownを記述すると、以下のように表示されます。
1 | // 本文とは切り離した場所に複数行のプログラムコードを表示させます |
inline code インライン・コード
インライン(本文中にプログラム・コードを含める)でコードを記述するには`
1つで囲みます。
1 | 本文中にコードを表示するには`console.log("hoge");`と記述します |
上記のようにmarkdownを記述すると、以下のように表示されます。
本文中にコードを表示するにはconsole.log("hoge");
と記述します
del 打ち消し
打ち消しを表すには~
2つで囲みます。
1 | ~~打ち消したい文字~~ |
上記のようにmarkdownを記述すると、以下のように表示されます。
打ち消したい文字
生成されるHTMLタグは以下のようになります。
1 | <del>打ち消したい文字</del> |
kbd キーボード
キーボードはmarkdownではサポートされていないため、タグを直接記述する必要があるようです。markdownはhtmlが混在していてもそのまま表示してくれます。
1 | キーボードは<kbd>Alt</kbd>のように記述します |
上記のようにhtmlを記述すると、以下のように表示されます。
キーボードはAltのように記述します
blockquote 引用
引用を表すには>
と半角スペースを先頭に記述していきます。また引用のネストも可能です。
1 | > 引用 |
上記のようにmarkdownを記述すると、以下のように表示されます。
引用
引用のネスト
サイトの引用
Yahoo(サイト名)
Yahoo! - yahoo
hexoで使える独自タグ
次に、静的ファイルジェネレータのhexoで独自に定義された便利なタグや、プラグインから利用できるタグをご紹介したいと思います。
excerpt 記事の抜粋や概要
hexoから標準で使えるタグです。記事のmarkdown中に<!-- more -->
を記述すると、それ以前の文章が概要扱いとなり、read moreをサポートしているhexoテーマなどで概要表示ができます。また検索エンジンの結果で表示されるmeta descriptionにも使われる場合があります。
1 | moreの直前に記述した文字列は概要として扱われます。 |
Read moreの表示例 (以下URLの3つ目の記事を参照)
hexoテーマ - landscape
toc 目次の自動生成
こちらもhexoで使えるタグです。tocとはthe table of contentsの略で、意味は目次です。hexo-tocというプラグインをインストールすると使えるようになります。
1 | $ npm install hexo-toc --save |
markdownで記述した文中のh2
〜h6
タグを収集し、目次をリスト表記で生成してくれます。こちらの記事でも前半で目次を貼り付けていますので、表示例は当記事の前半にてご確認ください。
1 | この直下に目次が生成されます。 |
youtubeやvimeoの埋め込み
こちらもhexoから標準で使えるタグです。markdownに動画を埋め込むには、https://www.youtube.com/watch?v=
の後ろに続く動画のID動画を記述していきます。
1 | {% youtube VtL0LAHLEY4 %} |
上記のようにmarkdownを記述すると、以下のように表示されます。動画の埋め込みの表示例はこちら。
youtubeの動画を埋め込む。
引用元のyoutube動画:https://www.youtube.com/watch?v=VtL0LAHLEY4
vimeoの動画を埋め込む。
引用元のvimeo動画:https://vimeo.com/27246366
flickrの画像を埋め込む
こちらはプラグインのhexo-tag-flickrをインストールすると使えるタグです。flickrのPhoto IDを指定するだけで、簡単に画像を埋め込むことができます。インストールはnpmから可能です。
1 | $ npm install hexo-tag-flickr --save |
hexo-tag-flickr
github - hexo-tag-flickr
markdownには以下のように記述します。photo
は生成されるimgタグに指定したいクラス名(複数指定可)、b
(=長辺1024px)は表示される画像のサイズの指定です。
1 | {% flickr photo 24286149303 b %} |
上記のようにmarkdownを記述すると、以下のように表示されます。flickr画像の埋め込み例はこちら。
instagramを埋め込む
こちらもプラグインによって埋め込み可能です。hexo-tag-instagramをインストールすると、短い記述で埋め込みができます。
1 | $ npm install hexo-tag-instagram --save |
hexo-tag-instagram
github - hexo-tag-instagram
1 | {% instagram https://www.instagram.com/p/3yNx8hE6iE/ %} |
上記のように記述するとインスタグラムの投稿記事をブログに表示させる事ができます。
引用元のポスト:https://www.instagram.com/p/3yNx8hE6iE/
twitterツイートを埋め込む
こちらもプラグインによって埋め込み可能です。hexo-tag-twitterをインストールすると、短い記述で埋め込みができます。
1 | $ npm install hexo-tag-twitter --save |
hexo-tag-twitter
github - hexo-tag-twitter
1 | {% twitter https://twitter.com/tea0828/status/819885806714138624 %} |
上記のように記述すると、以下のように表示されます。
引用元のツイート:https://twitter.com/tea0828/status/819885806714138624
Sound Cloudのトラックを埋め込む
こちらもプラグインによって埋め込みが可能です。hexo-tag-soundcloudをインストールすると、短い記述で埋め込みができるようになります。
1 | $ npm install hexo-tag-twitter --save |
hexo-tag-soundcloud
github - hexo-tag-soundcloud
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が埋め込まれる便利なタグです。
1 | $ npm install hexo-tag-googlemaps --save |
hexo-tag-googlemaps
github - hexo-tag-googlemaps
markdownには以下のように記述します。以下の15
は地図のズーム倍率です。100%
は表示される幅、250px
は高さとなります。
1 | {% googlemaps 35.3129923 138.5873496 15 100% 250px %} |
google mapの地図の埋め込み例はこちら
画像の比較(jQuery TwentyTwenty)
画像でビフォー・アフターをスライド表示させます。hexo-tag-twentytwentyを使うと、簡単な記述で比較画像を表示させることができるようになります。
1 | $ npm install hexo-tag-twentytwenty --save |
記述方法は、markdownに、以下のtwtw
タグを記述するだけでOKです。before.jpg
はビフォーの画像。after.jpg
はアフターの画像になります。
1 | {% twtw before.jpg after.jpg %} |
上記のように記述すると、以下のように表示されます。
応用編!hexoで独自に定義したタグを使う
hexoでは通常のmarkdown記述が利用できる上に、前述したような便利な独自タグをプラグインから利用できるようになっています。しかし、これでも不十分である場合には独自にプラグイン開発するか、themes/your-theme/scripts
下でタグを定義することもできます。詳しくはhexo.extend.tag.register
について解説されてるオフィシャルサイトのドキュメントをご覧ください。
hexo
hexo - tag
実装例1:Instagramの投稿記事を埋め込むHexo markdownタグ
独自定義するタグの実装例をいくつか挙げたいと思います。まずは、先程も例を挙げたインスタグラムの投稿記事を埋め込むプラグインを見ていきたいと思います。前述と同じ説明になりますが、下記のコードはタグを記述して、簡単にインスタグラムの埋め込みHTMLを生成させるものです。
1 | {% instagram 8ppwIyE6lU %} |
上記のようにmarkdownを記述すると、以下のように表示されます。
引用元のinstagram記事:https://www.instagram.com/p/8ppwIyE6lU/
上記のタグが機能するように、themes/your-theme/scripts/extend.js
で以下のように定義しました。コードの処理内容を説明すると、タグに渡される記事のショートコードを元に、Instagramの埋め込みHTMLを返します。メリットとしては、以下のコードを最新の内容にメンテナンスすることで、全ての記事対して最新の埋め込みコードが適用できる点です。
1 | hexo.extend.tag.register('instagram', function(args, content){ |
こちらはプラグインとして、実際にnpmに公開していますのでインストールして使うこともできます。
実装例2:注意書き欄のHTMLを生成するHexo markdownタグ
続いて、もう一つ実装例をご紹介したいと思います。Hexoの記事でBootstrapのAlertsみたいな注意書き欄を簡単に表示させたいなと思いました。そこで当ブログでは、注意書きの欄をmarkdownから簡単に生成できるように、hexo.extend.tag.register
で独自タグを拡張定義しています。markdownの記述例は以下のような形です。
1 | {% tag_round att 注意書きのサンプルタイトル %} |
上記のようにmarkdownを記述すると、以下のように表示されます。
注意書きのサンプルタイトル
タグの中で注意書きの本文を記述します。こちらの中でもmarkdown
の記法が使えます。
上記のタグが機能するように、themes/your-theme/scripts/extend.js
で以下のように定義しました。ここで一つ注意点ですが、通常タグで囲ったテキストは関数に渡される文字列として扱われるので、markdownとしてHTMLにレンダリングされません。そこで、hexoのmarkdownレンダラにも使用しているmarkedを使ってrequire
してHTMLにレンダリングさせます。
1 | var mk = require('marked'); |
(備録)markdownのエディタとWebツール
markdownのエディタはSublime text 3を使っています。またWebページ上でmarkdownの結果をすぐに確認したい時にはRemarkableやDillingerを使っています。Remarkableは2つの画面で構成されていて、左側にmarkdownを記述していくと瞬時にHTMLへ変換してくれる大変便利なサービスとなっています。Dillingerも同様のサービスです。
markdownを速攻プレビューできる「Remarkable」
Remarkable DEMO
最後に
いかがだったでしょうか?今回はmarkdownの一般的な記法と、ブログジェネレータのhexoで使える独自タグ、またその拡張方法について触れました。markdownで記事を書く際や、タグの拡張を検討されている場合の参考にして頂ければ幸いです。