投稿にMarkdownは便利

記事
IT・テクノロジー

投稿にMarkdownは便利

GitHub の Readme ファイルなどに活用されているMarkdownですが、便利な記法です。 このブログの原稿も基本的に Markdown で書いています。

以前は HTML で書いて投稿していた時期もありますが、最近は Markdown を活用しています。

描き方はシンプル

HTML などに比べると、書き方のルールはシンプルです。 HTML よりは遥かに短い時間でマスターできると思います。見出しには「#」の数を帰るだけで設定できますし、メタデータも埋め込むことができます。投稿のタイトルや日付など、実際には表示させないでデータを残すことができるので、後でプログラムによる分類や検索にも活用できます。

(*)詳細の文法についてはインターネットに沢山ドキュメントがあるのでそちらを参照してください。

そのままでも読みやすい!

Markdown 記法は元々は、HTML よりシンプルな記法で記述した文章を HTML に変換する目的で開発されたようですが、現在では、HTML 以外でも他の標準的な文書に変換するユーティリティも広く開発されています。

一番のメリットは、Markdown で書かれたドキュメントもそのままでも読みやすい形になっています。

Atom や VSCODE などのエディタでは、プラグインを入れたりすると実際に HTML に変換したイメージをプレビューしながら入力することも可能です。しかし、元々の記法がシンプルで HTML などと違い、Markdown の形式のままでも普通に読むことができるので扱い易くなっています。

ソースコードも取込みやすい

HTML で書く場合、ソースコードなどの記述は取り込むのが苦手です。 HTML のタグを示すのに使う「<」や「>」などもコード引用の形式で扱えば、コードをコピー&ペーストするだけで特殊記号と組み合わせて記述する必要はありません。この記事のようにソースコードを引用する事が多い原稿の場合、Markdown で書くほうが効率よく原稿の作成ができます。

プログラムで扱いやすい

既に書いていますが、Markdown では、メタデータを表示するデータとは別に扱う事ができます。 このブログの原稿の場合、

* タイトル
* 投稿日時
* 内容の概要
* 内容の分類
などをメタデータに入れています。実際の投稿は HTML に変換されているためにそれらのデータは利用者からは見えなくなっています。これらのデータは投稿の管理にはとても便利で、メタデータを読み出す事で、実際のページを生成する場合などに役立てています。

例えば、ファイルのタイムスタンプではなく、メタデータの日時によって並び替えたり、Web サイトで原稿を表示する際に、一覧の中で内容の概要を紹介したりするのに利用できます。 私が、運営しているブログサイトでは、サーバー側のレンダリングで投稿を表示していますが、その表示の元データはこのメタデータを読み込んで作成していました。現在の実装は、メタデータを Firebase のデータベースに入れておいて、それを読み込むことで表示のパフォーマンスの改善をしています。

この方法だと、サイトを再構成したりする場合、データベースを作り直す必要がある場合もあります。しかし、メタデータを読み込めば、ある程度自動で投稿記事のインデックスデータの自動生成ができるので便利です。

こうした機能は、テスト用で公開用とは別に Firebase のプロジェクトを作ってテストする場合など、サイトの複製を作る際にも活躍します。こうすると、全く同じデータをテスト用の Firabase プロジェクト上に複製する際も簡単にできます。

Markdown 関連の処理は豊富

また、自分の Web サービスなどで利用する場合にも便利です。npmに Markdown を扱うパッケージが多数公開されていて簡単に自分のサービスに取り込めるので便利です。表示は HTML を利用してダウンロードする際は別のフォーマットに変換したりするようなことも可能です。

実際に、Web ページで変換した Markdown を表示する際に利用できる CSS ファイルもインターネットで公開されているので、そうした既存の仕組みを使えば、簡単でしかも短時間で本格的なドキュメントの表示の仕組みが自分のサービス内で提供できます。

* markd
* gray-matter


などのパッケージが便利です。 こうしたパッケージには、メタデータの取り出しや本文の HTML 変換など便利な機能を既に実装してあるので、機能を呼び出すだけで、必要なデータを取り出すことができます。

HTML に変換してしまえば、簡単に必要なページの場所にドキュメントを埋め込むことが簡単にできます。

まとめ

Markdown はドキュメントを作成する際に非常に便利な記法です。 プログラムとの相性もよく、公開されているユーティリティも豊富なので簡単に自分のサービスに取り込めるのは大きな魅力です。また、ソース(Markdown 形式の原稿)も HTML などに比べると遥かに一般の人にも読みやすい形式なので扱い易くなっています。

GitHub などの Readme ファイルも Markdown が使われており、知っていると何かと便利なドキュメント記法です。
サービス数40万件のスキルマーケット、あなたにぴったりのサービスを探す