Markdown 書くとき、何に気を付けてる？
今では様々な場所で採用されている Markdown 記法。 ソフトウェアエンジニアの皆さんなら、きっと一度は書いたことあると思います。
ちょっとした文書をさっと書くときにも便利ですね。 Word みたいな重い文書作成ソフトを開かなくていいし、かといってメモ帳とかで書くよりも見やすく整形して閲覧できるし。
そんな Markdown を書いたとき、だいたい Markdown プレビューで表示して、HTML に変換された後の見た目をチェックしたりしますよね。 ...ここでちょっと待ってください。HTML での見た目を優先しすぎていませんか？
おおもとの Markdown と方言
本題に入る前に、Markdown の種類を整理しておきます。
Markdown には、おおもとの記法と、そこから派生した方言的な記法があります。
GitHub、Qiita、Stack Overflow などなど、Markdown はさまざまなサービスで採用されています。 このはてなブログの記事も Markdown で書いています。 実は、それらの Markdown は、おおもとの Markdown を拡張や改変した書き方です。
例えば、Markdown で表を描いたことのある人も多いかと思いますが、おおもとの Markdown の仕様には表を描く記法なんてありません。 それぞれのサービスで、表を描けるように仕様が追加されています。 他にも、打消し線やシンタックスハイライトなど、おおもとの Markdown には無い記法も使えるようになっています。
それらの記法は、各サービスでちょっとずつ仕様が違っています。つまり方言ですね。
Markdown の哲学
ここで、おおもとの Markdown の仕様を見てみましょう。 下記サイトです。
...英語ですね。でも大丈夫。私がなんとか訳してみます。
イントロダクションに、Markdown の構文の設計方針が書いてあります。
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
「最も重要な設計目標は、『できるかぎり読みやすく』です。タグや整形用の記法でマークアップされるのではなく、プレーンテキストとして公開できるようにするべきです。」って書いてあります。 同じ事が、Syntax のページにも書いてあります。この考えが、おおもとの Markdown では最も重要視されています。
そうです。 HTML での見え方とか、細やかに見た目を調整できるとかではなく、プレーンテキストとしての見た目に重きが置かれています。
まぁ、文章中に <br/> とか <li> とか \setlength{\textwidth}{40zw} とか出てきたら読みにくいですよねー。
完全にノイズです。
(ただ、html タグは使えます。ど～～～しても HTML の見た目を優先したいって人向けに、html タグが使えるようになっているのだと思います。)
Markdown を書くときの心構え
Markdown がそのような哲学で仕様が定められているのなら、Markdown を書くときもその哲学に沿って書くようにした方がいいと思います。 つまり、「プレーンテキストとして読みやすい Markdown を心がけましょう」ということです。これが今回最も言いたかったことです。
Markdown は、HTML に変換できない環境ではテキストエディタを使ってプレーンテキストとして読まれるでしょう。 また、差分比較をするときもプレーンテキストとして比較されることが多いです。 なのでちゃんとプレーンテキストとして読まれることを意識しましょう。
表組みについて
さて、おおもとの Markdown には表組みの記法がありません。 これは、プレーンテキストとして見やすい表組みの書き方ができなかったからだと推測しています。 例えば、次のような Markdown はどうでしょう。
|チーム名|人数|コメント|
|----|----|----|
|マックスボンバーズ|3|頑張ります。|
|暇人|5|暇人が5人あつまってこのチームを作りました。意気込みとかはないですが、暇なので練習する時間はたっぷりあったので、おそらく優勝すると思います。コメントもついつい長くなっちゃいました。暇なので。|
|セクシーコマンドー部|2|ウォンチュッ！！|
見にくいですね。列がバラバラです。 表は、データを並べて項目を比較しやすくしたいときに使われます。列が揃っていてなんぼなのに...。 こういう書き方になってしまうので、おおもとの Markdown では採用されなかったのだと推測しています。
表については、書きたくなることは結構ありますし、私も書きます。 表を全く用いないのは厳しいものがあります。 その場合は、列を揃えた方がいいと思います。
そのためにも、表の中に文章を書くことは避けましょう。列が揃いにくいですし、表が横に長くなります。 表はあくまでデータを並べるためのもので、○とか×とかの記号や数値、一単語程度の語で構成されるのが理想ですね。
そもそも、表の中に文章を書かなければいけない状況というのは、文章構造に問題があるというサインなのかもしれません。 その場合は、見出しを作って、普通の段落として説明するなり、文章構造を見直してみてはどうでしょうか。
まとめ
Markdown を書いたときは、まず「プレーンテキストとして読みやすいこと」を心がけましょう。その次に「HTML として見やすいか」をチェックしましょう。(まぁ、プレーンテキストとして読みやすい文書は、だいたい HTML でも見やすいです。)
