対象読者

マークダウンをはじめテキスト拡張をご存知でない方
- メモ帳に書くように文字以外のレイアウトを気にしていない方
WordPressや無料ブログについているリッチテキストエディタ（記事を書く時に便利なアイコンがついているWebエディタ）を愛用している方

本稿は今までのやり方を否定する意図はなく、マークダウンを知らない方向けであるため、エンジニア入門者を想定している。
なお、補助・参考教材として活用する事も検討しているため、難しい内容は扱わない。

謝辞

記事の性質上、また投稿プラットフォームの都合上Qiita上でのマークダウンについて言及しているが、他環境でも多少の変更や代替で同じことができるように意識をして筆を執っているが、必ずしも全てに対応できているわけではない。

アウトプットの質にこだわる意味

先日も触れたが、学びの質を高めるため（インプットの質を上げるため）にアウトプットもしっかるやろう、という事で本稿がある。
未読の方はそちらも確認されたい。

先の記事の言葉を使うなら、本稿のアウトプットの質を高めるというアプローチは前提としてWeb媒体での公開を想定している。

マークダウンを使って表現の幅を広げよう

後述するが他の書き方もある中でマークダウンを採用したい。
マークダウンは一般に多くのエンジニア系Webシステムにおいて市民権が圧倒的であることと、脱初学者を目標にした場合は敢えてマイナーなところに手を出す事もないだろう。
もちろん、マークダウンを使っていて他の書き方も覚えて、その上で比較するのは問題ない。

たとえば、学生がレポートで使用する場合はマークダウンではなくLaTexがよく採用されるため、こちらの話をすべきだと考えているが、一般にWeb上で公開するという目的に対して高機能であり、環境構築面の課題があるため本稿では取り扱わない。
ただし、将来的にはLaTexは使えた方が良いのは事実であり、特にデータサイエンティストを目指すなら数式が書きやすいので非常にお勧めしたい事を明記しておく。

フリーフォーマットではダメなのか？

ダメではないが、せっかく便利な機能があるなら使った方がよい、という考え方。
たとえば、HTMLを知っているなら使えた方が良いよね、とかそれぐらいの話でしかない。
誤解を恐れずに言えば、これらの書き方はHTMLタグを手打ちするよりは楽だよね、という発想である。
たとえば、リッチテキストエディタなどはこれらに近い機能をドラッグ+アイコンクリックで文字の装飾ができるが、同じ考え方である。

はじめてマークダウンを学ぶ際のアプローチ

マークダウンに限った話ではないが、自分で辞書を作るつもりで学ぶのがよい
たとえばチートシートを作る、クイックスタートガイドを作るとか
特にクイックスタートは自身で管理運用をしていくと保守のノウハウもたまるのでおすすめ

よく使うもの

慣れないうちは２画面で確認しながら書いていくのがおすすめ。

見出し。たとえば、本章の「よく使うもの」という文字も見出しタグ（HTMLタグにおけるh3タグ）を使っている
リストタグ。これ
強調タグ

次にコードコメント二種類 の違いを見ておこう。

複数行
のコード

と、メールでもよく使う

引用

は覚えてしまってもよい。

他の書き方もできるが、慣れるまでは使わないし、慣れても他のきほうは頻度が高くないので調べながら書くぐらいで良い。

なお、マークダウンのオリジナルの拡張がある（Qiitaも含む）ので、標準的なマークダウンと拡張には気を付けよう。
たとえば、筆者がよく使うものに

note機能

:::note
note機能
:::

があるが、これはQiitaのマークダウン拡張なので他では使えない。
ただし、似たような機能に対応する代替的な書き方があるものもある。
Zennだと:::noteが:::messageと、若干書き方が異なる。

各プラットフォームでマークダウンの拡張が違うという事は留意してほしい。
そして、違いを確認したいならチートシートを探すと良い。

別のサービスでも拡張を使いたい！

ニーズとして結構多いと考えている。私にとっては注釈¹であったり、アコーディオンなのだが、サービスやHTMLタグの種類によっては許容されている事も知っておこう。

たとえば、以下のようにアコーディオンを実装できる。

ここをクリックで開閉

ここに本文がいっぱい。
インナー要素（ここでは傾き） や以下のようなブロック要素

引用（ブロック要素例）

アコーディオン部分はここまで。

アコーディオンのHTMLタグ例

<details>
<summary>ここをクリックで開閉</summary>

---

ここに本文がいっぱい。
*インナー要素（ここでは傾き）* や以下のようなブロック要素

> 引用（ブロック要素例）

アコーディオン部分はここまで。

---

</details>

これだけだと個人的にはちょっと素っ気ないというか、こだわるならsummaryタグはボタンっぽくクリックしたらアクションが起こりそうな印象を与えるよう視覚的に変えたいとかはあるので、必要に応じて対応しよう。

マークダウンのベストプラクティス

よく受講生から質問を受けるので章として分けたが、そもそもベストプラクティスはあるのだろうか？
書きやすさと読みやすさはある一定の範囲までなら比例の関係にあるが、真に読んでいて楽しめるテキスト、ビジュアルコンテンツを作る場合は書きやすさと読みやすさは比例の関係ではなくなってしまうというのが筆者の意見だ。
てあれば、どこまで読みやすくするかは個々人の判断になるが、極端な労力をとして書きやすさを犠牲にするくらいなら、アウトプットの内容自体にこだわるべきであるという考え方だ。
ただし、読みやすいデザインそのものをテーマとしてとらえた場合はこの限りではない。しかし、読みやすさと書きやすさの関係性には目を向けてもらいたいと考えている。
あくまでマークダウンは執筆を補助するものであって、マークダウンのために文書を書くことがあってはならない。

Tips: コンテンツの品質が高いとは？

ここまではテキストを中心に見てきたが、本質的に文字も視界に入ったもの（見えるもの）と考えると、それは一つの絵であるといえる。
特定の絵のパターンや羅列を我々は文字と呼び、意味があることを理解しているにすぎない。そして、人間は五感を持っている。
見える情報だけでなく、聞く、嗅ぐ（匂い）、触る、味などの方法からも情報を得る事ができる。Webに限って言えば見る・聞くだろうか。UIを通じて「触る」もできそうだ。
特に「見る」において、文字→イラスト→動画、特に動きや光などで刺激を強くすることで印象付けやすくなるし、同じように音もBGMや効果音などにも受け取る印象が異なるだろう。
本旨から外れるが、ゲーム（エンターテイメント）を研究してみるのが近道だと考えている。

話を戻そう。
特にプログラミングにおいてアウトプットをするという点にフォーカスしていくと、主に文字情報になるだろう。
その文字情報を視覚化（羅列ではなく、イラストっぽく見えるように寄せていく）する方法を検討していきたい。
たとえば、Pythonを勉強しているならmatplotlibを使ってグラフを書く事があると思う。
同様にJavaScriptならChart.jsが使いやすい。

なお、様々な方法でレポーティングをシステムからやって欲しいという要望はよくあるので、知っておくと便利だ。

なお、マークダウンでもテーブルを扱う事ができる （ものがある） ので、リストよりはテーブルを使うようにするとそれっぽい印象を与えることができる。

注釈

【一般化してほしいマークダウン記法】 注釈はこんな感じになる。 ↩