Markdownを素敵なHTMLに変換するツール3選

📝 ウェブ制作制作雑記

Published @2021-07-29 (Thursday) Updated @2021-07-29 (Thursday)

執筆者 : 清水公太

Table of Content

はじめに

マークダウンファイルをHTMLファイルに変換するツールは様々ありますが、その中の個人的なベスト3を紹介致します。

目次（Table of Content）を自動生成したり、サイドナビを設置したりする事ができるため、私は特に、資料作成や構築したサイトのマニュアル等の取り扱い説明書を作成する際に重宝しています。

これまでWordやPowerPointなどで作成していたものが、マークダウンで手軽に作れるようになったため、手放せないツールたちです。

マイベストツール3選

以下の3つがマイベストです。この3つに優劣があるわけではなく、それぞれ素敵なポイントがあります。

StackEdit
Pandoc
Docusaurus

StackEditについて

概要と特徴

StackEdit(スタックエディット)は、ブラウザで動作するオープンソースのマークダウンエディタです。

エディタである事に加えて、GUIメニューも豊富なので、3つのツールの内、最も簡単に利用出来きます。

UIは英語ですが、難解な英語ではありませんし、比較的直感的に利用できるかと思います。

公式サイト
StackEdit – In-browser Markdown editor

エディタ
StackEdit

StackEditのエディタ画面

PWAとして実装されているため、PCにインストールして利用する事も可能で、オフラインでも動きます。

私はテキストのみの資料や、外部サイトの画像ファイルを読み込んで設置するような資料の場合は、StackEditをよく利用します。ローカルマシンの画像を設置する場合は、後述の2つのツールを利用します。

StackEditの特徴や気に入っている点は以下の通りです。

直感的に使えるため、学習コストがかからない
PWAのため、PCにインストールでき、Windowsメニューから呼び出す事が可能
オフラインでも動作する
ファイルをフォルダ別に整理する事ができる（情報はブラウザのローカルストレージに保存されます）
パブリッシュ機能があり、WordPressアカウントへ追加したり、DropboxやGoogle Driveといったストレージに保存する事ができる
スクロールに応じて追従する目次(Table of Content)を自動生成してHTMLファイルを作成することができる
出力したHTMLファイルは、それ単体でページとして成り立つ
出力したHTMLファイルはローカルマシンでも閲覧できる(ウェブサーバーが不要)
ワークスペースを複数設定できる(例えば複数のGoogle Driveを切り替える事ができる)
編集履歴が保存される

主な機能のスクリーンショット

各部の概要

左側が入力パネルで、その情報が右側にプレビューされます。また、左側のサイドナビゲーションではファイルを整理できます。

右側のナビゲーションから様々なメニューにアクセスできます。

パブリッシュ機能

WordPressやDropbox、Googleアカウントと連携することで、各種サービスにファイルを追加するパブリッシュ機能があります。 WordPressへのパブリッシュは使った事はないのですが、便利そうですね。

私はこのパブリッシュ機能をストレージへの保存のためによく活用しています。

HTMLファイルのエクスポート

StackEditのHTMLエクスポート機能では、目次付きのHTMLも出力できます

一番下の "Styled HTML with TOC" を選択すると、以下の画像の用に追従する目次付きのHTMLファイルをエクスポートできます。
目次にはアンカーリンクも適用されています。

StackEditが向いていないケース

資料内にローカルPCの画像を設置する場合です。

StackEditでは、Markdown記法で画像を挿入する事もできますし、メニューから画像を挿入する事もできます。

ただ、画像はURL形式で挿入する必要があります。
ローカルPCの画像へのファイルパスを入力しても、StackEdit上でプレビューができません。

このような場合は、私は、PandocかDocusaurusを利用しています。

理由としては、これら2つのツールは基本的にマークダウンファイルをVisual Studio Codeなどのコードエディタで作成する事が多く、コードエディタのプラグインを利用すると、画像や動画ファイルへのパスを補完してくれて作業効率が上がるためです。

Pandocについて

概要と特徴

Pandoc(パンドック)は、CLIで操作するオープンソースのドキュメントコンバーター(文書ファイルの変換ツール)です。

マークダウンファイルをHTML形式に変換する事はもちろん、Microsoft Word、XML、Wiki等、あらゆる文書形式に対応しています。

公式サイト
Pandoc - About pandoc

Pandocはコマンドで操作するのですが、ドキュメント資料用にマークダウンファイルをHTMLファイルに出力する事に特化すれば、使うコマンドは1つ覚えればOKです。

また、初期状態では、Pandocで出力されたHTMLファイルにはシンプルなCSSしか適用されていませんが、GitHubに公開されているテンプレートを利用する事で、素敵なスタイルが適用されたページを作成できます。

私は、マークダウンファイルにローカルマシンに保存している画像や動画を挿入する場合はPandocを利用しています。

画像や動画をimagesディレクトリ等で整理して、それをマークダウンファイルに読み込み、PandocでHTMLファイルを出力した後に、imagesディレクトリを含むフォルダ毎、資料を提供したい相手に送るというような事をよく行います。

後述するDocusaurusは、複数ページにまたがるドキュメントサイトの構築には非常に強力な機能が提供されているのですが、エクスポートしたファイルはウェブサーバーがないと閲覧できないため、各々のローカルマシンで閲覧する事が前提になる場合は、Pandocが使いやすいのです。

Pandocの特徴や気に入っている点は以下の通りです。

CLIで利用する
あらゆる文書ファイルフォーマットがサポートされている
出力ファイルのためのテンプレートを自作できる
他の方が公開しているテンプレートも利用できる
出力したHTMLファイルは、それ単体でウェブページとして成り立つ
CSSを追記する事でデザインを調整できる(StackEditでも同様ですが、CSSをテンプレートに追記しておく事で毎回追記する手間が無くなります)
出力したHTMLファイルはローカルマシンでも閲覧できる(ウェブサーバーが不要)

インストール方法

Windowsの場合はインストーラーが提供されているため、これが一番簡単です。バイナリが格納されたZIPファイルも提供されています。

いずれも以下からダウンロードできます。

Release pandoc 2.14.1 · jgm/pandoc

インストールが完了している事を確認するには、ターミナルを立ち上げ、以下のコマンドを実行します。

pandoc -v

これでPandocのバージョンが表示されれば、インストールは完了です。

より詳細な情報を知りたい場合は、以下の公式サイトをご確認ください。

公式サイト
Installing pandoc

Google翻訳による日本語版
pandocのインストール

テンプレートのダウンロード

私の場合は、データエンジニアのRyan GroseさんがGitHubに GNU General Public License v3.0 で公開している easy-pandoc-templates をよく利用させて頂いています。

テンプレートファイル群は以下よりダウンロードできます。

easy-pandoc-templates
ryangrose/easy-pandoc-templates: A collection of portable pandoc templates with no dependencies

マークダウンファイルの変換方法

ここでは、上記でダウンロードした「easy-pandoc-templates」を利用して、マークダウンファイルをHTMLに変換する方法を紹介します。

まず、ディレクトリ構造は以下のようにしておきます。

your-directory
├── your-markdown.md
└── easy-pandoc-templates-master

なお、easy-pandoc-templates-masterフォルダには、ダウンロードしたファイル一式をそのまま入れておいてください。

次に、ターミナルを立ち上げ、マークダウンファイルのあるディレクトリまで移動します。

そして、以下のコマンドを実行します。

pandoc -s --toc --template=easy-pandoc-templates-master/html/elegant_bootstrap_menu.html your-markdown.md -o your-markdown.html

コマンドの内容は以下の通りです。

-s : スタンドアロンのページを作るオプションです。これにより、headタグなどが付与されたHTML文書として独立したHTMLページが生成されます。
-toc : Table of Content(目次)を生成するオプションです。
--template : テンプレートファイルのURLかファイルパスを指定します。ここでは、elegant_bootstrap_menu.htmlというテンプレートを利用します。
your-markdown.md : 変換したいマークダウンファイル名を指定します。
-o your-markdown.html : アウトプットするファイル名を指定します。

このコマンドを実行すると、移動したワーキングディレクトリにHTMLファイルが出力されます。

以下のように、左側に追従する目次が生成されます。

elegant_bootstrap_menu.htmlにCSSやJavaScriptを追加することで、見た目の調整やスムーススクロールを適用させる事もできます。

Docusaurusについて

概要と特徴

Docusaurus（ドキュザラス）は、Facebookが開発しているドキュメントサイト作成ツールです。

StackEditはHTMLファイルが出力できるマークダウンエディタ、Pandocはコマンドによる文書変換ツールですが、Docusaurusは静的サイトジェネレータ(Static Site Generator)です。

そのため、HTMLページを1ページ作成するというより、複数ページによるウェブサイトを作成する場合に重宝します。

Docusaurusの特徴や気に入っている点は以下の通りです。

静的サイトジェネレータ（Static Site Generator）である
ドキュメントサイトの構築が得意
マークダウンファイルを静的サイトに変換してくれる
Reactをサポートしている
多言語化サイト用の機能がある
ドキュメントのバージョン管理機能がある
サイト内検索機能（Algolia documentation search）をサポートしている
デプロイ機能がある

なお、ドキュメントサイトの構築向けツールではあるものの、ホームページ(トップページ)や会社概要などの独立したページ（WordPressでいう固定ページ）、ブログページなども作成できます。

私の場合、Docusaurusはページ数の多いマニュアルを作成する際に重宝しています。

ただし、Docusaurusは、ビルドした静的サイトの閲覧にはウェブサーバーが必要です。つまり、ローカルマシンにあるHTMLファイルをブラウザにドラッグ&ドロップしてfile://のURL形式で閲覧するという事ができません(方法をご存じの方がおりましたら是非 @ktsmz までご一報ください！)。

そのため、公開したくないサイトの場合は、IPアドレスによるアクセス制限等を行う必要があります。

この件に関しては、以下のGitHub Issueで議論されています。
Support Relative Path · Issue #448 · facebook/docusaurus

使い方

Docusaurusの使い方は、ここで説明するにはボリュームが大きいため、以下の記事にまとめていますので、ご覧ください。