ドキュメントやブログを書く際、ふと「これってどう書くんだっけ？」とMarkdownの記法を思い出せなくなることがあります。私自身ようやく最近、まとめを作っていきたいなと思いだし、先日hugo+cloudflare pagesで公開を始めています。ですが、久しくmarkdownを触っていなかったこともあり、だいぶ基礎を忘れているので、自分の復習を兼ねつつまとめて行こうと思います。
また、次はhugoを使ったサイト展開のまとめも作りたいと考えています。
Markdownで一番使うであろう見出し
Markdownにおいて見出しとして記載するときは#を使います。##の数だが増えるとだんだん小さくなります。下記はそのサンプルです。
私のマイルールになりますが、基本は##を使います。サイズ感がちょうどいい気がしています。
それにもし、大項目を作りたくなっても、簡単に追加できますしね。
サンプル
|
|
ぬるぽ
ぬるぽ
ぬるぽ
ぬるぽ
ぬるぽ
ぬるぽ
ぬるぽ
文章の改行
Markdownはある程度自動でレイアウトを整えてくれるのですが、その反面、自分自身で改行をしたいと思っても、うまくできないことが多々あります。下記はその一例になります。
|
|
こう書いたとしてもですね。
構成はコードで管理するけど、障害対応はだいたい手動。ドキュメントも書いたはずなのに、気づけば最新版は記憶の中。
こうなってしまうんですよね。なぜかしら改行してくれない。
んでこれに対する方法は私は3つほど使っております。
HTMLの<br>タグを入れてあげる
これが一番制御しやすい気がしますが、噂によると<br>タグの乱用はあんまりよくないと聞いたことがあります。
それでは具体的にやってみましょう
|
|
| 監視アラートは鳴らなかった。でもユーザからの電話は鳴った。 ログに何も残ってないときが一番怖い。 |
|---|
ちゃんと改行されていますね。
エンターダブル連打で改行
Makrdownさん。Enter一個だと改行してくれません。では例を見てみると
|
|
こう入力しても？
| サーバは仮想でも、運用ミスはリアル。そろそろ自分にもスナップショット機能が欲しい。 |
|---|
改行してくれません。ですが、改行を二つ入れると？
|
|
サーバは仮想でも、運用ミスはリアル。
そろそろ自分にもスナップショット機能が欲しい。
というようにちゃんと改行してくれます。
スペース二つ入れる方法
えぇ実はこれ私も知らなかったのですが、改行したいところに二つスペース入れて改行すると改行してくれるらしいです。
|
|
サーバは仮想でも、運用ミスはリアル。
そろそろ自分にもスナップショット機能が欲しい。
ほんとだ。この機能は知らなかったですね。<br>タグ入れるより手軽ですね。
ただ、注意点もあって、これは半角スペース二つなんですよね。
日本語で文章記載していると全角で入れてしまうことが多々あって、これを気を付けないときれいに改行してくれないので要注意です。
三つの比較
<br>タグで改行
再起動すれば直るのはわかってる。でも理由がわからないと怖い。
「様子見します」は最後の希望。
エンター連打で対応
再起動すれば直るのはわかってる。でも理由がわからないと怖い。
「様子見します」は最後の希望。
スペース二つ入れる方法
再起動すれば直るのはわかってる。でも理由がわからないと怖い。
「様子見します」は最後の希望。
このような違いが生まれますので使用はお好みでどうぞ
コードブロック
例えばコマンドを書くときに
en
conf t
erase startup-config
reload
てかくのは見た目的にちょっとイケてないです。そんな時はバッククォートを使います。
```
en
conf t
erase startup-config
reload
```
とこんな具合に書くと。
|
|
という具合にイケてる見た目になります。``` (バッククォート三つ)で囲めばOKです。ちなみにこの内部は改行一行で問題なく改行してくれます。
ちなみにこのコードブロック、対応している言語はハイライト表示をしてくれるらしいのですが、私はインフラ系で開発のことはわからないので割愛します。Ciscoとか対応してるんかなぁ。してないだろうなぁ。んなわけでネットワーク系では単純なコードブロックとして使うのが無難かなぁと思います。ちなみにBashなどには対応していたはずなのでサーバー屋さんはぜひ使ってみてください。
エスケープ処理
たとえば文章を書いていたとして、下記のような文章を書こうと思ったとします。
「障害が起きても大丈夫、心がもう落ちてるから。」
フォールトトレラントなメンタル
ハイ、唐突に見出しになってしまいます。こういう時にどうすればいいのかはこちら
\ (バックスラッシュ)を使えばよいのです。こちらを使うと
\# フォールトトレラントなメンタル
と記載できます。これでmarkdownに読み込ませると。
#フォールトトレラントなメンタル
というように記号を文字として読み込ませることができます。
リストの作成。
まぁこちらについては手動で対応してもいいのですが、面倒ですよね
・Ansible？あぁ、手動の代わりに事故るやつね
・障害報告書を自動生成したい。でも障害を減らすのが先だった
・Terraformでインフラを構築する前に、自分のメンタルをterraformしたい
・ログに何も出てないときが一番怖い
まぁこれでも読めるには読めますが、ちとめんどいです。そこで-を使います
|
|
- Ansible？あぁ、手動の代わりに事故るやつね
- 障害報告書を自動生成したい。でも障害を減らすのが先だった
- Terraformでインフラを構築する前に、自分のメンタルをterraformしたい
- ログに何も出てないときが一番怖い
こんな感じ。注意点として- (ハイフン)の後ろには一つスペースを開けること。
何回かミスりました。
インデントを使うことで、階層構造を構築することもできるみたいです。
まとめだよっ！
今回はmarkdownで使える記法をまとめてみました。
Markdownは、手軽に書ける反面、奥の深い記法です。シンプルな構文で構成されていますが、文書の構造を意識したり、読み手への配慮を取り入れたりすることで、格段に伝わりやすいコンテンツになります。
特に、ブログやドキュメント、メモといった幅広い用途で活用できるため、自分なりのテンプレートやルールを決めておくと、作業の効率も上がります。
今回ご紹介した内容が、Markdownの基礎を振り返るきっかけや、新たな気づきにつながれば幸いです。今後も必要に応じて使い方を見直しつつ、自分の表現スタイルをアップデートしていきましょう。(write by chatGPT)