クモのようにコツコツと

フロントエンドエンジニア イイダリョウのブログ。略称「クモコツ」

【HTML】MarkdownをGulpでHTMLにコンパイルしてみる

メタ言語の続きです。前回はStylusをGulpでCCSにコンパイルしました。今回はMarkdownをHTMLにコンパイルしてみる。それでは行きましょう!

【目次】

※参考:【CSS】StylusをGulpでコンパイルしてみる - クモのようにコツコツと

※参考:メタ言語(HTMLテンプレートエンジン、AltCSS、AltJS)まとめ qiita.com

MarkdownはMarkupの対義語だった!

「マークダウン」という名前はHTMLのM(Markupマークアップ)の対義語らしい。なるほど、そういうことだったんだ!

Markup と Markdown

  • Webでは Markup Language が使われてきている。
  • Markup Language では < > で囲んだタグを使うことが多い
  • Marup の煩雑さ(手入力するとしたら)に対するアンチテーゼとして、Markdown の考え方が提唱され使われるようになった。

※参考:Markdown入門

markdownは以前、HTMLテンプレートエンジンをまとめた記事でも触れたように、簡単なHTMLより簡単な記述で書ける書式。

※参考:【Emmet, Haml, Markdown, Slim, Pug】HTMLテンプレートエンジン事始め - クモのようにコツコツと

例えば見出しタグが

<h1>見出しです</h1>
<p>本文です。本文です。本文ですったら本文です。</p>

ハッシュだけで済んだりね。

# 見出しです
本文です。本文です。本文ですったら本文です。

「はてなブログ*1」や「Qiita」「GitHub」などにも採用されている。共通書式のため異なるサービス間でも移行がしやすいのが魅力と思う。

フォルダ作成→移動→package.json作成→Gulpインストール

さっそくやってみる。準備はこれまでと同じ手順でいけると思う。

node.jsとnpmは入っている前提(下記のコマンドでバージョン番号が出る)

node -v
npm -v

次にコンパイルを実行したいフォルダを作成する。今回は「gulp_markdown」とする。

ターミナルのcdコマンドでフォルダに移動する

cd /(フォルダ)/gulp_markdown

package.jsonを作成

npm init -y

ローカルにGulpインストール

npm install -D gulp

いつもと同じ流れ。次から固有な内容。

パッケージ(gulp-markdown)をインストールする

markdownをコンパイルするツールはいくつかあるようでどれが良いのかよくわからない。

ひとまずこちらの記事を参考にさせていただきGulpのパッケージ「gulp-markdown」をインストールしてみる。*2

※参考:gulp で markdown から html と pdf を生成してみる - Qiita

インストール!

npm install -D gulp-markdown

インストールに成功するとpackage.jsonに追記される。

  "devDependencies": {
    "gulp": "^4.0.2",
    "gulp-markdown": "^5.0.1"
  }

ファイルを作る

このような構成。

gulp_markdown
├md
|└index.md
└gulpfile.js

Markdownの拡張子は.mdか。

(上記の他にnode_modulesフォルダ、package-lock.json、package.jsonもある)

gulpfile.jsにgulp.task()を記述

公式ページを参考に

※参考:GitHub - sindresorhus/gulp-markdown: Markdown to HTML

const gulp = require('gulp');
const markdown = require('gulp-markdown');

exports.default = () => (
    gulp.src('md/index.md')
        .pipe(markdown())
        .pipe(gulp.dest('dist'))
);
  • 変数gulpgulpを読み込む
  • 変数markdowngulp-markdownを読み込む
  • exports.defaultプロパティの値は無名関数。
  • 無名関数の中はgulp.src().pipe().pipe()とチェーンになっている
  • src()の引数はindex.mdのパス
  • 一つ目のpipe()の引数はmarkdown()で、引数にオプションはなし 二つ目のpipe()の引数はgulp.dest()distフォルダに吐き出す

exportsっていつものtask()と違う書き方。Gulp4からはこちらが推奨されているらしい。

※参考:gulp4に移行するためにタスクを書き換えてみた | 福岡のホームページ制作会社・メディア総研株式会社 マグネッツ事業部

ただ、処理の中身(.src()とかpipe()とか)の書き方は変わらないようだ。

Markdownファイルを作成

index.mdの中身を書く。

以前、HTMLテンプレートの記事で書いた「Markdown」の内容を元に。

※参考:【Emmet, Haml, Markdown, Slim, Pug】HTMLテンプレートエンジン事始め - クモのようにコツコツと

See the Pen Markdown practice 1 by イイダリョウ (@i_ryo) on CodePen.

# マークダウン記法
見出しは「# 」をつける。
## 見出し2
「##」が2つだと見出し2になる。
### 見出し3
「###」が3つだと見出し2になる。

改行2つで段落になる。
アスタリスク1つで*イタリック*。
アスタリスク2つで**太字**になる。

そのほか色々な記法がある。こちらを参照。

※参考:Markdown 記法 サンプル 一覧 - Qiita

コンパイル実行(文字化ける。。)

いよいよコンパイル実行!

HTMLの本文(bodyタグ)の外側のheadタグやhtmlタグ、DOCTYPE宣言とかどうするんだろ?という疑問があるんだが…。まあとりあえずコンパイルしてみるか。

今回の書き方ではタスク名を設定していないのでgulpだけで動かすようだ。

npx gulp

お、distフォルダとindex.htmlがでけた。

gulp_markdown
├dist
|└index.html
├md
|└index.md
└gulpfile.js

開いてみると…Oh、文字バケとる。。(半分予想ついてたがw) f:id:idr_zz:20200327073119j:plain

HTMLコード

<h1 id="マークダウン記法">マークダウン記法</h1>
<p>見出しは「# 」をつける。</p>
<h2 id="見出し2">見出し2</h2>
<p>「##」が2つだと見出し2になる。</p>
<h3 id="見出し3">見出し3</h3>
<p>「###」が3つだと見出し2になる。</p>
<p>改行2つで段落になる。
アスタリスク1つで<em>イタリック</em>。
アスタリスク2つで<strong>太字</strong>になる。</p>

やはり、マークダウンで書いたところが変換されるだけだね。

実際に使う際はこの本文部分をHTMLのbodyタグに埋め込む仕組みを考える必要がありそう。

必須タグはHTMLタグ直書きしちゃう!

お、こちらの記事ではHTMLの必須タグを直書きしている!

※参考:Markdownを使うのに環境構築なんて不要!? - Qiita

いっちょやってみっか〜*3

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>マークダウン&HTMLテスト</title>
</head>
<body>
<section>

# マークダウン記法
見出しは「# 」をつける。
## 見出し2
「##」が2つだと見出し2になる。
### 見出し3
「###」が3つだと見出し2になる。

改行2つで段落になる。
アスタリスク1つで*イタリック*。
アスタリスク2つで**太字**になる。

</section>
</body>
</html>

試しにhtmlタグbodyタグ、headタグとかも入れてみたゾ。

リベンジ!

npx gulp

おお、今度は文字化けない! f:id:idr_zz:20200327074119j:plain

HTMLコードも意図通り!

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>マークダウン&HTMLテスト</title>
</head>
<body>
<section>

<h1 id="マークダウン記法">マークダウン記法</h1>
<p>見出しは「# 」をつける。</p>
<h2 id="見出し2">見出し2</h2>
<p>「##」が2つだと見出し2になる。</p>
<h3 id="見出し3">見出し3</h3>
<p>「###」が3つだと見出し2になる。</p>
<p>改行2つで段落になる。
アスタリスク1つで<em>イタリック</em>。
アスタリスク2つで<strong>太字</strong>になる。</p>
</section>
</body>
</html>

そうか、確かにブログ書いてる時にもiframeタグとかを埋め込むときとかはHTMLタグを直書きしているしな。markdownとHTMLは共存可能なわけか!これで解決。

最後に

ということでmarkdownのコンパイルに成功しました。markdownはHTMLタグと共存可能なので、複雑な処理はHTMLで書けばいいですね。DOCTYPEなどの必須タグも。

実際に運用する際には、ページ全部をmarkdownで書くのではなく外側の部分はテンプレートエンジンやJSフレームワークを使って、本文テキスト部分をmarkdownで量産する、という形になると思われる。Reactの静的サイトジェネレータ「GatsbyJS」とか。

gulpはtask()ではなくexportsの書き方は今後主流になって行くのだろうか。その流れも知れてよかったです(gulpを使わずにnpm scriptだけで完結する流れもあるのだが)

それではまた!


※参考:メタ言語(HTMLテンプレートエンジン、AltCSS、AltJS)まとめ qiita.com

*1:当ブログで利用

*2:markdonwってHTMLだけでなくPDFも作れるん?素敵!

*3:悟空