Hajimeの妄言とTechの部屋

このブログでは、テック系の話や、ドキュメントに関する話などをエンジニアが「こんな感じに使うとええんじゃね？」ということを書き連ねるブログです。

Webエンジニアが書く。Markdown覚書(おぼえがき)とテクニック

テクノロジー Markdown Tech HTML

はじめに

今回は改めて、「Markdownとは何ぞや」から始まり、「こんな使い方できるよ〜」まで、Webエンジニアの私が持つ知見を総動員してまとめてみました。
18,000字を超える*1長文になっていますが、覚書として活用いただければ幸いです。

作成の背景

今日は前回初めて投稿したブログが、ブログとしてあまりにも体裁が整っていなかったので、「きちんとしよう。」ということで書き直しました。

Markdown とは

Markdownは文章の書き方です。 デジタル文章を活用する方法として考案されました。 (中略) Markdownはジョン・グルーバー（John Gruber）によって2004年に開発され、最初は Daring Fireball: Markdown で公開されました。その後、多くの開発者の手を経ながら発展してきました。 *2

とあるように、Markdownは文章の書き方、つまり方法を示しています。
TeXを使って文章を書いたことがある方はそれと同じ感覚です。
使ったとこのない方は、Microsoft Wordのエディタ画面の一番上の文字のスタイルを変更したりするツールバーを全く使わないで「文章の中にキーワードを入れると変更したいスタイルを実現する書き方」といった認識で大丈夫でしょう。

豆知識

IT業界もしくはプログラミング学習を今まさに始めている青少年たちはこのMarkdownという名称でピン! ときて欲しいところなのですが、このMarkdownはウェブページを作る際に最も利用されているHTMLととても関連があります。
HTMLの正式名称はHyperText Markup Languageです。
正式名称を思い出して∑( °д°) ハッとした方はすでにお気づきかと思いますが、HTMLはHyperTextをマークアップ言語で記述した文章という意味があります。 MarkdownはHTMLのタグなどをわざわざ書かずに、もっと簡単にHTML文章を書く方法(正確にはHTML文章に変換することができる書き方)です。
逆にいうと、Markdownの表示する機能(DocbaseもGithubもAtomのViewerも)は多くがHTML変換され表示されているので、直接MarkdownにHTMLタグを入れても下のように表示することが可能なものがあります(これを見てワクワクした人は僕と同じ人種なのでいい酒が飲めそう*3 )。
現に、Markdownを書く際に文字の大きさを大きくしたりする際は<span style="CSSのstyle">何かの文書</span>のように追加されるかと思います。
それだけではなく下記のようなタグも実は使うことができます。(docbaseはinput,progress,meterタグが使えませんのでご注意ください。)

名称 タグ 例
Input Text <input type="text" />
Input Password <input type="password" />
Checkbox <input type="checkbox" checked /> この記事は面白い
Input Color <input type="color" />
Input Range <input type="range" />
Progress <progress value="0.3" /> 動画ダウンロード中
Meter <meter value="0.7" /> 七割五分

本記事の構成

前置きが長くなっていますが、「0章：はじめに」はこの節で終わりです。
次の章は目次になっています。
Markdownの書き方をそのまま順番に列挙しても良いのですが、ある程度カテゴライズした方が読みやすかったりするかと思うので、本記事では下記のようなカテゴリ分けをします。

  • 文字変換系
    • 文章中の文字のスタイルを変換する書き方
  • 表示変換系
    • 文章の表示方法を変換する書き方
  • データ追加系
    • 文章内に文字列以外の情報を追加する書き方

本記事ではMarkdown特有の書き方と、HTMLを使った更に使える書き方を合わせてまとめています。
すべてのサンプルにはコードスニペットを使ってどうやって記載しているのかも表示しますので、実際にMarkdown表示できるエディタで確認してみてください。

では、長くなりましたが、ネタ画像とともに本編をどうぞ。

ブチャラティ_覚悟は良いか？

目次

目次一覧(クリックで目次が開きます)

確認環境

対象 詳細
はてなブログ 2019/10/14 現在環境
Github 2019/10/14 現在環境
Docbase 2019/10/14 現在環境
Atom Markdown Preview package (v0.159.28)

文字変換系

段落分け

記述方法

文章の間に1行空行を挟む
段落と言っても、文頭にスペースが勝手に入るわけではないので注意。

サンプル

プププランドの食べものが、デデデ大王とその手下たちによってすべて奪われてしまった！

このままではおなかが空いてしまいます。

はるかぜとともに降り立ったのは、若者「カービィ」！！ *4

プププランドの食べものが、デデデ大王とその手下たちによってすべて奪われてしまった！

このままではおなかが空いてしまいます。

はるかぜとともに降り立ったのは、若者「カービィ」！！

環境特性

対象 一言
はてなブログ -
Github -
Docbase 文中で改行するとそのまま改行されるので、空行入れて文頭に空白を入れればそれっぽくなります。
Atom -

改行

記述方法

行末に半角スペースを2つ入れて改行

サンプル

プププランドの食べものが、デデデ大王とその手下たちによってすべて奪われてしまった！
このままではおなかが空いてしまいます。
はるかぜとともに降り立ったのは、若者「カービィ」！！

プププランドの食べものが、デデデ大王とその手下たちによってすべて奪われてしまった！__(←半角スペース2つ)
このままではおなかが空いてしまいます。__(←半角スペース2つ)
はるかぜとともに降り立ったのは、若者「カービィ」！！

環境特性

対象 一言
はてなブログ -
Github -
Docbase 普通に改行するだけでOK
Atom -

斜字体

記述方法

_または*で斜字体にしたい部分を囲む

サンプル

私は、星のカービィシリーズが大好きです。

私は、_星のカービィシリーズ_が大好きです。

環境特性

対象 一言
はてなブログ -
Github -
Docbase -
Atom -

強調(Strong)

記述方法

__または**で強調したい部分を囲む

サンプル

私は、星のカービィシリーズが大好きです。

私は、**星のカービィシリーズ**が大好きです。

環境特性

対象 一言
はてなブログ -
Github -
Docbase -
Atom -

斜字体 + 強調

記述方法

___または***で斜字体かつ強調したい部分を囲む

サンプル

私は、星のカービィシリーズが大好きです。

私は、___星のカービィシリーズ___が大好きです。

環境特性

対象 一言
はてなブログ -
Github -
Docbase この書き方はできないので、*__<囲みたい部分>__*とするといい感じ
Atom -

打ち消し線

記述方法

~~で打ち消したい部分を囲む

サンプル

私は、星のカービーカービィシリーズが大好きです。

私は、星の~~カービー~~カービィシリーズが大好きです。

環境特性

対象 一言
はてなブログ -
Github -
Docbase -
Atom -

色変更

記述方法

Github特有の書き方は無し。HTMLのstyleオプションで表現する。

文書の一部の色を変える場合(ほとんどこれだと思いますが)はspanタグを使うことが多いです。

色の指定はこちらのカラーコード(原色大辞典*5 )を参照ください。

サンプル

私は、星のカービィシリーズが大好きです。

私は、<span style="color: #ff69b4;">星のカービィ</span>シリーズが大好きです。

環境特性

対象 一言
はてなブログ -
Github 使用不可(色を変える手立てはない…。)逃げ道は下記
Docbase -
Atom -
Githubの場合の逃げ道

github-diffcolor

```diff
- 私は、星のカービィシリーズが大好きです。(Red)
+ 私は、星のカービィシリーズが大好きです。(Green)
# 私は、星のカービィシリーズが大好きです。(Gray)
```

文字サイズ変更

記述方法

色変更の際と同様。
Github特有の書き方は無し。HTMLのstyleオプションで表現する。

サンプル

私は、星のカービィシリーズが大好きです。

私は、<span style="font-size: 200%">星のカービィ</span>シリーズが大好きです。

環境特性

対象 一言
はてなブログ -
Github 使用不可(おとなしく見出しを使えとの思し召し)
Docbase -
Atom -

上付き文字

記述方法

abbrタグとsupタグを利用

サンプル

(カービィ) = (可愛さ)3+(スタッフの愛 ✕ ファンの愛)2

<span>(カービィ) = <abbr>(可愛さ)<sup>3</sup>+(スタッフの愛 ✕ ファンの愛)<sup>2</sup></abbr></span>

環境特性

対象 一言
はてなブログ 数式なら数式のインプットがあるらしいのでそれを使うほうがいい感じ
Github 使える
Docbase 使える
Atom -

下付き文字

記述方法

abbrタグとsubタグを利用

サンプル

(カービィ) = (可愛さ)3+(スタッフの愛 ✕ ファンの愛)2

<span>(カービィ) = <abbr>(可愛さ)<sub>3</sub>+(スタッフの愛 ✕ ファンの愛)<sub>2</sub></abbr></span>

環境特性

対象 一言
はてなブログ 数式なら数式のインプットがあるらしいのでそれを使うほうがいい感じ
Github 使える
Docbase 使える
Atom -

ルビ

記述方法

いろいろな書き方があるが、ここではruby、rtタグを使うやり方を掲載
(最も多くの環境で有効だから)

サンプル

星のカービィ食いしん坊

星の<ruby>カービィ<rt>食いしん坊</rt></ruby>

環境特性

対象 一言
はてなブログ -
Github -
Docbase あまり想定していない挙動なので、若干崩れるので注意
Atom -

表示変換系

見出し(Header)

記述方法

#を先頭につける。
つける数が多いほど小さい見出しになる。

サンプル

H1

H2

H3

H4

H5
H6
# H1
## H2
### H3
#### H4
##### H5
###### H6

環境特性

対象 一言
はてなブログ 最大6こ
Github 最大6こ
Docbase 最大5こ
3階層までの見出しが自動で目次として出力される
Atom -

コードスニペット(インライン)

記述方法

対象の部分を`で囲む

サンプル

私は、星のカービィシリーズが大好きです。

私は、`星のカービィシリーズ`が大好きです。

環境特性

対象 一言
はてなブログ -
Github -
Docbase -
Atom -

コードスニペット

記述方法

対象のコードを```で囲む
最初の部分に該当ファイルの言語を記述すると、その言語に応じたコードスニペットが適応される。

サンプル

const Kirby = [...Array(100).keys()].map((i) => `${i}番目のカービィ`)
const getKirby = (index) => {
  if(!isFinite(index)) return 'デデデ大王'
  if(index < 0) return 'ワドルディ'
  if(index >= 100) return 'メタナイト'
  return Kirby[index]
}

console.log(getKirby(Math.round(Math.random() * 100))) // Note: ○番目のカービィ
console.log(getKirby('DDD')) // Note: 備えあれば嬉しいな。※
console.log(getKirby(-10)) // Note: ワド
console.log(getKirby(1000)) // Note: メタ

※ *6

```javascript
const Kirby = [...Array(100).keys()].map((i) => `${i}番目のカービィ`)
const getKirby = (index) => {
  if(!isFinite(index)) return デデデ大王'
  if(index < 0) return 'ワドルディ'
  if(index >= 100) return 'メタナイト'
  return Kirby[index]
}

console.log(getKirby(Math.round(Math.random() * 100))) // Note: ○番目のカービィ
console.log(getKirby('DDD')) // Note: 備えあれば嬉しいな。
console.log(getKirby(-10)) // Note: ワド
console.log(getKirby(1000)) // Note: メタ
```

環境特性

対象 一言
はてなブログ -
Github 言語ではなくファイル名の拡張子でスニペットを適応してくれるいい子
Docbase 同上
Atom -

リスト

記述方法

-や+、*を行頭に置き、半角スペースを挟んで文章を記述 記号の前に2つ以上の半角スペースを入れることで、入れた数に応じたインデントもつけられる。

サンプル

※ 環境破壊は気持ちいいゾイ！ とは
アニメ星のカービィで、デデデ大王が発した名(迷)言の一つである。 

- 主要キャラクター
  - カービィ
  * デデデ大王
  + ワドルディ
  - メタナイト
- 主要ボスキャラクター
  - ウィスピーウッズ
    - 環境破壊は気持ちいいゾイ！
  - クラッコ
  - ギャラクティックナイト
    * 別名しいたけ
- 倒せないキャラクター
  - ゴルドー
  - ゼボン

環境特性

対象 一言
はてなブログ 前後は空行である必要がある。
Github -
Docbase -
Atom -

番号付きリスト

記述方法

リストの記号部分を<半角数字>.に変えるとできる
数字は連番でなくても連番になる。

サンプル

  1. 星のカービィ
    1. 1992年
  2. 星のカービィ 夢の泉の物語
    カービィのピンボール
    1. 1993年
  3. (中略)
  4. 星のカービィスターアライズ
    • 2018年
  5. スパーカービィハンターズ
    • 2019年
1. 星のカービィ
    1. 1992年
2. 星のカービィ 夢の泉の物語<br>カービィのピンボール
    1. 1993年
10. (中略)
11. 星のカービィスターアライズ
    + 2018年
12. スパーカービィハンターズ
    * 2019年

環境特性

対象 一言
はてなブログ 順序付きの場合は4つ以上インデントを開けないとキレイに表示されないことがある。
リストと同様に前後を空行にする必要がある
Github -
Docbase -
Atom -

CheckBox

記述方法

リストと似た感じで- [ ]を先頭に記述する。
チェック済みの場合は- [x]とする。
リストと同様にインデントを設定できる。

サンプル

カービィは可愛い
この記事は面白い
はたらけ！ ニート *7

- [x] カービィは可愛い
- [x] この記事は面白い
- [ ] はたらけ！ ニート

はてぶでの実現方法

<input type="checkbox" checked /> カービィは可愛い<br>
<input type="checkbox" checked /> この記事は面白い<br>
<input type="checkbox" /> はたらけ！ ニート

環境特性

対象 一言
はてなブログ はてぶのMarkdownではinputタグを使うしかない(リロードしたら戻るので使えないのとほぼイコール)
Github -
Docbase -
Atom -

Table

記述方法

枠をそれっぽく書く(サンプル見るのが一番早い)
2行目の指定により列の、右寄せ、左寄せ、中央揃えが決まる
tableの幅はウィンドウサイズを最大として、中身の要素の大きさに応じていい感じに変わる(←これ重要)
もしセルの結合等をする場合はtable、th、tr、td タグを用いる必要があるため、注意。

サンプル

タイトル コンテンツ
テキスト入力 サンプルテキスト。長い文章の場合は改行が勝手にされます
タグ 任意の位置で改行したい場合などは
htmlタグを駆使することでうまく表示されます。
画像 IMG
IMG IMG 
| タイトル | コンテンツ |
| :---| :---: |
| テキスト入力 | サンプルテキスト。長い文章の場合は改行が勝手にされます |
| タグ | 任意の位置で改行したい場合などは<br>htmlタグを駆使することでうまく表示されます。 |
| 画像 | <img src="img-url.jpg" width="128" alt="IMG"> |
| ![IMG](img-url.jpg) | ![IMG](img-url.jpg) |

環境特性

対象 一言
はてなブログ -
Github 行頭と行末の|は省略可能
Docbase -
Atom 行頭と行末の|は省略可能

アコーディオン

記述方法

detailsタグにより囲むことで実現可能
summaryタグによりアコーディオンの名称を設定可能

サンプル

開くで

IMG
画像みたいな大きなものも格納しておける 
echo "We love Kirby!"

<details>
<summary>開くで</summary>

| ![IMG](https://hajime-tools.firebaseapp.com/static/img/HajimeToolsHome.a5ecf1e.jpg)  |
| :---: |
| 画像みたいな大きなものも格納しておける |

`echo "We love Kirby!"`

</details>

環境特性

対象 一言
はてなブログ -
Github -
Docbase details内にmarkdownの短縮表記使用不可(htmlタグだけを使えば可能)
Atom details内にmarkdownの短縮表記使用不可(htmlタグだけを使えば可能)

データ追加系

リンク

記述方法

インラインの場合[表示する文字列](URL)の形式で 自動リンクの場合は<URL>の形式で
あまり知られていないですが、[と]でキーワードを作成し、キーワドに対応するURLを外だしにしてまとめる方法もあります。
別タブで開く場合はMarkdownで各方法がいろいろWeb上に転がっていますが、環境による依存が激しいので、おとなしくaタグを使って <a href="URL" target="_blank">表示する中身</a> としたほうが良いです。

サンプル

https://www.google.com/
googleへのリンク
カービィポータルは星のカービィに関するコンテンツ(キャラクターやカービィの歴史)を提供しています。

<https://www.google.com/>  
[googleへのリンク](https://www.google.com/)  
[カービィポータル]は星のカービィに関するコンテンツ([キャラクター]や[カービィの歴史])を提供しています。

[カービィポータル]: https://www.kirby.jp/
[キャラクター]: https://www.kirby.jp/character/
[カービィの歴史]: https://www.kirby.jp/history/

環境特性

対象 一言
はてなブログ 基本的にリンクをコピペしようとすると、どんな感じで入れるか聞かれるので
それを選んだほうが早いです
Github -
Docbase URLを貼るとそのままリンクが作成されるので、<>で括る必要はありません。
Atom -

注釈

記述方法

[^<<注釈番号>>] の形式で基本的には記述し、内容を[^<<注釈番号>>]: <<内容>>というように記述する。
はてぶでは ((<<注釈の内容>>)) のような形で記載することができる。 リンクの容易性や、自動で番号を振ってくれるので、はてぶを利用する場合は書きを利用するほうが良いだろう

サンプル

テレビのお陰で意味無いけど健全な娯楽を！嘘だけど迅速なる報道を！無駄だけど楽しいＣＭを！どれでもタダで楽しめるゾイ！*8 才能は無いけど根気だけはある物好きは腐るほど居るでゲス1

環境特性

対象 一言
はてなブログ 特殊記法を使ったほうが良い
Github 使えない
Docbase 使えない
Atom -

画像

記述方法

![<<画像名(alt要素名)>>](画像URL) の形式で利用可能。
ローカルファイルの場合はローカルのパスを指定する。
筆者は

  1. GithubのIssueから画像をアップロード
  2. そのURLだけ取得。
  3. issueを消す

上記の方法で利用しています。

  • パブリックリポジトリのissueであれば誰でもリンクを知っていれば見ることができる
  • プライベートリポジトリなら、該当のメンバーしか参照できない
  • 画像自体はキャッシュされるので、githubが落ちても一度見たことのある画像であれば表示可能
    • キャッシュが貯まるのでそこだけは注意

ちなみに、圧倒的にファイルをアップロードして使うことが多く早いので、アップロードして良いファイルならアップロードしましょう。
(書き間違いとかもなくなるよ)

サンプル

IMG *9

![IMG](https://www.nintendo.co.jp/wallpaper/KirbyStarAllies_thanks/img/KirbyStarAllies_thanks_1920_1080.jpg)

環境特性

対象 一言
はてなブログ アップロードするだけ
Github アップロードするだけ
Docbase アップロードするだけ&省略記法で画像サイズ指定も可
![](IMG_RUL.jpg=100x100)
Atom きちんと書こう(T_T)

iframe

記述方法

基本的にはコンテンツを提供しているwebサイト上に共有等の操作が有り、そこから埋め込み等を選ぶことでiframeタグを取得することができる。
はてぶの場合は独自フォーマットが有り、アップロード時に選択するだけなのでそちらを利用したほうが楽。

サンプル

www.youtube.com

[https://www.youtube.com/watch?v=1vNmTih9IXI:embed:cite]

<iframe width="560" height="315" src="https://www.youtube.com/embed/FNPf9KkL-ik" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

環境特性

対象 一言
はてなブログ 独自フォーマット有り。リンクをアップロードするだけ
Github 使用不可
Docbase -
Atom 使用不可

その他

この章では、私の知るこんな「使い方ができるぞーっ」ていうモノのサンプルを書き連ねていきます。

Images on Table

はてなブログで魅せる。4コマ漫画
的なブログが増えたら面白いんだけどなぁ…。

f:id:DTM3110:20191014213306p:plain f:id:DTM3110:20191014213223p:plain
f:id:DTM3110:20191014213316p:plain f:id:DTM3110:20191014213243p:plain 
| ![img_3](https://cdn-ak.f.st-hatena.com/images/fotolife/D/DTM3110/20191014/20191014213306.png) | ![img_1](https://cdn-ak.f.st-hatena.com/images/fotolife/D/DTM3110/20191014/20191014213223.png) |
|:---:|:---|
| ![img_4](https://cdn-ak.f.st-hatena.com/images/fotolife/D/DTM3110/20191014/20191014213316.png) | ![img_2](https://cdn-ak.f.st-hatena.com/images/fotolife/D/DTM3110/20191014/20191014213243.png) |

Images on Links

Linkの書き方の中にImgを入れ込む方法。
画像クリックで任意のウェブページに遷移可能。
コレによって擬似的な画像ボタンが出来上がり。
ボタンの画像を作ったらいよいよwebページに変わってきそう。

IMG

[![IMG](https://www.nintendo.co.jp/wallpaper/KirbyStarAllies_thanks/img/KirbyStarAllies_thanks_1920_1080.jpg)](https://www.nintendo.co.jp/wallpaper/KirbyStarAllies_thanks)

コードスニペットの書き方 on コードスニペット

codeタグとpreタグおよびbrタグを使うことで、一応書くことができます。
preで囲っているのでスペースは反応しますが、改行はできないので、改行部分はbrタグを使ってください。

```markdown
私は、*星のカービィシリーズ*が大好きです。
私は、**星のカービィシリーズ**が大好きです。
私は、_**星のカービィシリーズ**_が大好きです。
```
<pre><code class="language-pascal">```markdown<br>私は、*星のカービィシリーズ*が大好きです。<br>私は、**星のカービィシリーズ**が大好きです。<br>私は、_**星のカービィシリーズ**_が大好きです。<br>```</code></pre>

終わりに

ここまでガッツリ書いてきましたが、まだまだサービスによってより良い書き方があったりします。
みなさんもいろいろ調べて、遊びまくってみてください。
また、「こんな使い方できるよ〜」というものがあればコメントください!!

参考

  1. HTML5リファレンス (最終参照: 2019/10/14)
  2. 日本語Markdownユーザー会 (最終参照: 2019/10/14)
  3. Wikipedia-マークアップ言語 (最終参照: 2019/10/14)
  4. Docbase-Markdownの書き方 (最終参照: 2019/10/14)
  5. @t_wkm2, Markdown再入門 (記載:2016年08月29日), (最終参照: 2019/10/14)
  6. @kamorits, Qiita マークダウン記法 一覧表・チートシート (記載:2017年09月27日), (最終参照: 2019/10/14)

  1. (注釈サンプル)アニメ星のカービィでのエスカルゴン大臣の名言の一つ。デデデ大王と揃って、このアニメではブラックユーモアあふれる名言でいっぱいである。よく土曜日の朝のアニメ枠で放送してたなこれ…。↩

*1:編集時の文字カウント見てます

*2:参照：日本語Markdownユーザー会 - Markdownの概要

*3:筆者はアルコールがアレルギー体質なので飲めません。

*4:星のカービィウルトラスーパーデラックス 「はるかぜとともに」タイトル説明 星のカービィウルトラスーパーデラックス攻略うぃきより抜粋

*5:名称指定する場合や16進数指定する場合の値も書かれていたり、色の名称で検索もできたりするので、オススメです。

*6:アニメ星のカービィでのデデデ大王の名言の一つ

*7: [official]はたらけ！ ニート feat.オワタP(弱音ハク、亞北ネル)より

*8: (注釈サンプル)アニメ星のカービィでのデデデ大王の名言の一つ。現代では絶対放送できないような内容である。

*9:https://www.nintendo.co.jp/wallpaper/KirbyStarAllies_thanks/