マークダウン記法まとめ

目次

1.はじめに
2.なぜマークダウンを学習するのか
3.コードの挿入
4.テキストの装飾
5.強調
6.打ち消し線
7.マークダウンの折りたたみ
8.補足説明
9.番号リスト
10.説明リストのタグ
11.チェックボックス
12.引用
13.水平線
14.リンク
15.画像埋め込み
16.テーブル
17.目次リンク
18.脚注
19.絵文字
20.リンクカード
21.ダイアグラム
22.コンテンツの埋め込み
23.コマンド補完機能
24.さいごに

1.はじめに

マークダウンの記事はインターネットで検索すれば同様の記事は出て来ますが、自分なりに見やすさを意識して記事の作成をしていこうと思います。この記事を見ていただければマークダウンの書き方が全くわからない人でもマークダウンの記法をマスターできると思います。

2.なぜマークダウンを学習するのか

markdownはgithubのレビュー時や、ドキュメント作成時に使うので、 習得は必須です。 markdownを使うとテキストだけで文字の装飾ができるので、 早くドキュメントを書くことができます。それでは早速ですが主な記法についてまとめていきます。

3.コードの挿入

バッククオート（```） で挿入したいコードを前後で囲むと下記のようにコードを挿入することができます。またファイル名を命名することでシンタックスハイライトが適用されます。

aaaaaaaa

qiita.rb

puts 'The best way to log and share programmers knowledge.'

4.テキストの装飾

#とテキストの間に半角スペースを入れるだけで自動的にテキストが装飾されます。#の数が多ければ多いほど文字は小さくなっていきます。

.書き方

# hhhh
## AAAA
###### BBBBB

結果

hhhh

AAAA

BBBBB

5.強調

_ か * で囲むとHTMLのemタグにすることができますQittaではitalic type になります。
また、__ か ** で囲むとHTMLのstrongタグになります。Qittaでは文字の太さを変えることができます。

前後に 半角スペース か 改行文字 を入れてくれてください。

.書き方

私が*GGG*になります。
金曜日に有給を使って**AAAA**に行きました。

結果
私が GGG になります。
金曜日に有給を使って AAAA に行きました。

6.打ち消し線

文字の打ち消し線を書きたい時は　~~ で囲むことで打ち消し線を書くことができます。

前後に 半角スペース か 改行文字 を入れてくれてください。

.書き方

ここに向かいたいのですが、~~ 道に迷っています。 ~~

結果
ここに向かいたいのですが、　道に迷っています。

7.マークダウンの折りたたみ

追加情報としたい内容を、detailsタグで囲みます。そして、折りたたみ部分のタイトルをsummaryタグで記載します。

.書き方

<details>
<summary>重要</summary>
何もないよ。残念でした。
</details>

結果

重要

何もないよ。残念でした🤪

8.補足説明

何かの注意事項として補足で説明文を加えたい時は、:::note infoと ::: で囲みます。
補足したい内容と:::note info と ::: はそれぞれ別の行にする必要があります。
noteの後のinfoは省略可能です。
説明文の追加スタイルは３種類あります。書き方は下記のようになります。

1. info※省略可能
2. warn
3. alert

.書き方

:::note info
インフォメーション
infoは省略可
:::

:::note warn
警告
警官に注意してください。
:::

:::note alert
より強い警告
押さないでください。
:::

結果

インフォメーション
infoは省略可

警告
警官に注意してください。

より強い警告
押さないでください。

9.番号リスト

1. 番号なしリスト
   文頭に*, +, -のいずれかを入れると順序なしリストになります
   箇条書きにしたい場合、便利です
   *, +, -の後には スペースが必要です

2.番号付きリスト
文頭に数字.を入れると番号付きリストになります。
数字.の後には スペースが必要です。

10.説明リストのタグ

HTMLの dlタグを用いることで書くことができます。
　dl（definition list）：定義リスト
　dt（definition term）：定義する言葉
　dd（definition description）：定義の説明

.index.html

<dl>
  <dt>バスケットボール</dt>
  <dd>アメリカ発祥のスポーツ</dd>
</dl>

結果

バスケットボール

アメリカ発祥のスポーツ

11.チェックボックス

番号なしリストの記述の後ろに[ ]を入れるとチェックボックスが生成されます。
チェックが入った状態のボックスを生成する場合は[x]を入力します。
前後にスペースが必要です。

.書き方

- [ ] 課題1
- [x] 課題2

結果

• 課題1
• 課題2

12.引用

文頭に>を置くことで引用になります。>>を２回重ねて書くと
ネスト部分を作ることができます。

複数行にまたがる場合、改行のたびにこの記号を置く必要があります。
引用の上下にはリストと同じく空行がないと正しく表示されません
引用の中に別のMarkdownを使用することも可能です。

.書き方

>この文章は引用です
>>この文章はネストです。

結果

この文章は引用です

この文章はネストです。

13.水平線

下記のように書くと全て水平線となります。

.書き方

* * *
***
*****
- - -
--------------------------------------

結果

---

---

---

14.リンク

下記のように書くとタイトル付きのリンクを作ることができます。

.書き方

[リンクテキスト](URL "タイトル")

結果
TED

15.画像埋め込み

.書き方

## タイトルありの画像を埋め込む
![代替テキスト](画像のURL "画像タイトル")

## タイトル無しの画像を埋め込む
![代替テキスト](画像のURL)

結果

補足：HTMLで入力すると画像サイズの調整などができます

.書き方

<img width="数値" src='画像URL'>

結果

16.テーブル

.書き方

3x3 

※xはエックス。テーブルは自動で作成される。文字は任意の文字。テーブルは
手動でも書くことは可能です。またHTMLでも記入することができます。(後述)

結果

A	AA	AAA
ABXCCC	knknn	fvnkidnvi
dkvkndmvkonm	kvevnoojmdvo	knviknv
vjojvo	jdvoewjov	dvcoewjov

.書き方(手動)

| Left align | Right align | Center align |
|:-----------|------------:|:------------:|
| This       | This        | This         |
| column     | column      | column       |
| will       | will        | will         |
| be         | be          | be           |
| left       | right       | center       |
| aligned    | aligned     | aligned      |

結果

Left align	Right align	Center align
This	This	This
column	column	column
will	will	will
be	be	be
left	right	center
aligned	aligned	aligned

HTMLで書く場合

.html

<table>
  <caption>HTMLの要素</caption>
  <thead>
    <tr>
      <th>名前</th> <th>説明</th>
    </tr>
  </thead>
  <tr>
    <td> table </td> <td>テーブル</td>
  </tr>
  <tr>
    <td> caption </td> <td>テーブルのキャプション</td>
  </tr>
</table>

結果

HTMLの要素

名前	説明
table	テーブル
caption	テーブルのキャプション

17.目次リンク

結論、下記のように書けば目次リンクを作ることができる。下記のコードをコピペして内容を修正して使用してもらった方が一番早い。
[]の内容は何でもいい。記載した内容は目次一覧に表示される。
()の内容は各章の名前と同じにする必要あり。同じにすると目次と各章がリンクする。
　　※下の例で言うと、「#1. はじめに」と「(#1はじめに)」を同じにする
　　※若干記載が異なるのは、ルールがあり半角スペースを「-」で表示するため

「#1. はじめに」以降の記載は、各章のタイトルを自由に記載すればいい。

#目次
[1.はじめに](#1はじめに)
[2.内容い](#2内容い)
[3.内容ろ](#3内容ろ)
[4.内容は](#4内容は)
[5.おわりに](#5おわりに)

#1. はじめに
#2. 内容い
#3. 内容ろ
#4. 内容は
#5. おわりに

18.脚注

論文など参考文献を記載するときによく利用される脚注ですが下記のように記述します。

『Markdownの脚注[^1]です。』
[^1]: 脚注を書きます

結果
『Markdownの脚注¹です。』

19.絵文字

絵文字を書きたい時は:を使って実現することができます。

.書き方

:kissing_closed_eyes:

結果

20.リンクカード

URLをリンクカードとして表示します。URLの前後には空行が必要です。

(空行)
https://qiita.com/Qiita/items/c686397e4a0f4f11683d
(空行)

(空行)
https://qiita.com/Qiita/items/c686397e4a0f4f11683d

結果

21.ダイアグラム

PlantUMLを使うことで文章内に図を表示することができます。
コードブロックの言語名をplantumlとすることで、PlantUMLによるダイアグラムを表示することができます。

.plantuml

Bob->Alice : Hello!

結果

他にもグラフを生成可能なマークダウン構文としてMermaidがあります。Mermaidとは、フローチャート、シーケンス図、クラス図、ガントチャート、およびgitグラフを生成するためのマークダウン構文です。書き方はPlantUMLと同じように書けばOKです。

.mermaid

sequenceDiagram
    autonumber
    actor お客様
    participant form as 申し込みフォーム
    participant s3 as 申込書補保管S3
    participant admin as 管理システム
    お客様->>form: サービス申し込み
    Note left of form: 申込書
    form->>s3: 申込書保存
    Note left of s3: 申込書
    form->>お客様: 受付処理中連絡
    s3->>s3: FSSによる申込書マルウェアチェック
    s3->>admin: 申込書マルウェアチェック完了通知
    admin->>s3: 申込書取得リクエスト
    s3->>admin: 申込書取得レスポンス
    Note left of admin: 申込書
    admin->>admin: 申込書バリデーションチェック
    admin->>admin: 申込情報登録
    admin->>お客様: 受付完了連絡

結果　

以下の記事でも使い方をまとめていますので気になる方は下記リンクをご覧下さい。

22.コンテンツの埋め込み

以下のサービスの埋め込みスクリプト/Embedタグが利用可能です。

・X（Twitter）
・CodeSandbox
・CodePen
・GitHub Gist
・Asciinema
・Figma
・Speaker Deck
・SlideShare
・Google Slides
・Docswell
・YouTube

詳しく確認したい方は下記のリンクを参照ください。

23.コマンド補完機能

/コマンドを入力することで、特定の操作や機能を直接呼び出すことができます。
使える機能は以下の通りです

機能	説明
codeblock	コードブロックを挿入します
alert	警告の補足説明を挿入します
warn	注意の補足説明を挿入します
info	補足説明を挿入します
commentout	コメントアウトを挿入します
details	折りたたみを挿入します
reference	脚注へのリンクを挿入します
footnote	脚注への注釈内容を挿入します
table	表を挿入します

24.さいごに

結構なボリュームになってしまいましたが、この記事でほとんどの記法が網羅されているので記法を忘れてしまって調べるのが手間だという方は是非ご活用下さい。

1. 脚注を書きます ↩