メインコンテンツへスキップ
見出し画像

Markdown 入門は、まず GitHub 風 Markdown から始めたい

    はじめに

    画像

    あ、あの…この記事は、みくくが担当します。ぱたぱた…。

    今回は Markdown について、入門向けにそっと整理してみます。
    難しいところを一気に覚えるというより、「まずここから始めると迷いにくいかも」という順番で、ゆっくり見ていけたらと思います。

    ただ、その前にひとつだけ、先に確認しておきたいことがあります。Markdown は、基本的には テキストファイル として書きます。えっと…ここでいうテキストファイルという言葉が、初学者には最初のつまずきになることがあるかもしれません。
    なので、いきなり記法へ進む前に、まずは「テキストファイルって何でしょうか?」というところから、少しだけ確認します。

    テキストファイルとは

    画像

    まず短く言うと、テキストファイルは 文字を保存するためのファイル です。

    テキストファイルとは、ざっくり言うと、文字をそのまま読める形で保存したファイルです。
    たとえば、次のような内容のファイルです。あの…とても素朴ですが、ここが Markdown の入口になります。

    こんにちは
    これはメモです

    Markdown ファイルも、このテキストファイルの仲間です。
    拡張子は `.md` がよく使われます。

    README.md
    note.md

    Windows のメモ帳や macOS のテキストエディットでも開けます。
    自分でエディタを入れるなら、Visual Studio Code やサクラエディタなども候補になります。

    画像、音声、動画、PDF、Word や Excel のファイルは、テキストファイルとは少し違います。
    こうしたファイルは、まとめて バイナリファイル と呼ばれることがあります。
    バイナリファイルは、専用のアプリで開くことが多く、テキストエディタで開いてもそのまま読めないことがあります。
    うぅ…ここは少しややこしいのですが、「Markdown は普通の文字として読めるファイル」と思うと、最初はかなり楽になると思います。

    文字エンコーディングは UTF-8 で

    画像

    テキストファイルには、文字をどう保存するかという 文字エンコーディング の話があります。
    ここも、初学者がつまずきやすいポイントのひとつです。
    本当は最初から細かく知らなくてもよい話なのですが、文字化けと関係するので、ここでは少しだけ触れておきます。

    Markdown 入門では、まず 新しく書くなら UTF-8 と覚えておけば大丈夫です。
    未来のことは…お話できません…ごめんなさい。でも、いま新しく書く Markdown については、UTF-8 を選んでおくのがいちばん無難かな、って思います。

    現在の Windows 11 のメモ帳で新しく保存する場合も、基本的には UTF-8 と考えてよいです。ただし、古い日本語ファイルでは Shift_JIS 系の文字コードが使われていることもあります。古いファイルを開いたときに文字化けする場合は、文字エンコーディングの違いを疑うとよいです。

    文字エンコーディングが合っていないと、本当はテキストファイルなのに、読めない記号の並びのように見えることがあります。
    感覚としては、「テキストのはずなのに、バイナリファイルを開いたときのように読めない状態になってしまう」ことがある、という感じです。
    もし文字化けを見つけても、あわわ…と慌てなくて大丈夫です。まずは文字エンコーディングを疑ってみる、くらいでよいです。

    Markdown とは

    画像

    Markdown は、このテキストファイルのよさを活かして、文章に少しだけ構造を付けるための書き方です。

    文章を書きながら、見出し、箇条書き、リンク、コード、表などを、なるべく軽い記法で表現できます。
    ただ見た目を飾るというより、「ここは見出しです」「ここは箇条書きです」「ここはコードです」という意味を、文章に与えていくイメージです。

    README、技術メモ、ブログ記事、Issue、Pull Request、ドキュメントなど、かなりいろいろな場所で使われています。
    えっと…思ったより日常の近くにいる記法、なのです。

    ただ、Markdown には少し困るところもあります。
    Markdown とひとことで言っても、実際には微妙に種類があることです。

    えっと…ここでいきなり細かい違いを追いかけると、入門記事としては少し大変になってしまいます。
    なので、この記事では方針を決めます。
    まずは GitHub 風 Markdown を基準にします。

    英語では GitHub Flavored Markdown と呼ばれます。略して GFM と書かれることもあります。

    GitHub の README、Issue、Pull Request などで使われている Markdown で、現在ではかなり広く通じる共通感覚(コモンセンス)に近いものになっていると思います。
    もちろん、これだけが正解という意味ではありません。けれど、最初の足場としては、とても頼りになります。

    もちろん、すべての環境が完全に同じ動きをするわけではありません。
    でも、最初に覚える Markdown としては、GitHub 風 Markdown を基準にしておくと、とても実用的です。

    Markdown は「文章を読みやすく保つ」ための記法

    画像

    Markdown のよいところは、書いたままの状態でも、そこそこ読みやすいことです。
    ここが、みくくはけっこう好きです。うぅ…恥ずかしいですけど、素のテキストが読みやすいのは、あとから自分を助けてくれます。

    たとえば HTML で見出しを書くと、こうなります。

    <h2>はじめに</h2>

    Markdown では、次のように書けます。

    ## はじめに

    どちらも見出しを表せます。

    でも、Markdown のほうが、普通の文章に近い見た目で読めます。
    この「書いている途中のファイルそのものが読みやすい」という性質は、思ったより大事です。
    自分であとから読み返すときも、ほかの人にレビューしてもらうときも、生成 AI エージェントに読ませるときも、Markdown は扱いやすい形になりやすいです。

    まず覚えたい見出し

    画像

    見出しを付けると、文章がいくつかのまとまりに分かれ、全体の構造が見えやすくなります。
    長い文章でも、「ここから何の話が始まるのか」が分かりやすくなります。
    あとから読み返すときにも、見出しを目印にして、必要な場所を探しやすくなります。
    あの…見出しは、文章の中の小さな道しるべみたいなものかもしれません。

    Markdown の見出しは、`#` を使って書きます。

    # 大きな見出し
    
    ## 章の見出し
    
    ### 章の中の小見出し

    表示すると、見出しとして大きさや階層が付いて見えます。

    大きな見出し

    章の見出し

    章の中の小見出し

    ここでは表示例として、あえて `#` から始まる見出しをそのまま置いています。
    そのため、この記事の画面上でも「大きな見出し」がかなり大きく見えます。

    これは Markdown の表示例としては仕様どおりです。
    ただし、Note のような記事本文では、見栄えや見出し構造を整えるために、実際には `##` から使い始めている実例も多いです。

    `#` の数が増えるほど、見出しの階層が深くなります。そして、多くの表示環境では、階層が深い見出しほど小さく表示されます。

    記事のタイトルには `#`、大きな章には `##`、その中の節には `###` を使う、くらいから始めるとわかりやすいです。
    なお、この「見出し」は英語では heading と呼ばれます。
    多くの場合、`#` は HTML の `h1`、`##` は `h2`、`###` は `h3` に対応します。

    段落は空行で分ける

    画像

    段落は、文字の塊を適度に分けるためのまとまりです。
    文章を段落で区切ると、長い文字の塊が分割され、読む人が内容を追いやすくなります。
    反対に、ずっと改行や空行がない文章は、どこで息継ぎすればよいのか分かりにくくなります。
    ただし、細かく分けすぎても、今度は文章の流れが切れすぎてしまいます。
    ひとつの話題や説明のまとまりごとに、ほどよく段落を分けるくらいが扱いやすいです。
    ドキドキ…長い文章ほど、空行が少しあるだけで、読む人の呼吸が楽になります。

    普通の文章は、そのまま書きます。

    これはひとつ目の段落です。
    
    これはふたつ目の段落です。

    表示すると、2つの段落として分かれて見えます。

    これはひとつ目の段落です。

    これはふたつ目の段落です。

    Markdown では、空行を入れると段落が分かれます。

    改行を入れただけでは、表示上の段落が分かれないこともあります。そのため、文章のまとまりを分けたいときは、空行をひとつ入れると覚えておくとよいです。
    また、Note のような読み物寄りの記事では、文や段落を短めにして読みやすくする文化的な傾向があります。
    そのような書き方をするときにも、空行で段落を分ける書き方はよく使われます。

    箇条書き

    画像

    箇条書きは、複数の項目を見やすく並べたいときに使います。
    文章の中に項目をそのまま並べると読みにくくなることがありますが、箇条書きにすると、ひとつひとつの項目が分かれて見えます。
    要点、材料、確認事項、短いメモなどを整理するときに便利です。
    えっと…頭の中で散らばっているものを、そっと机の上に並べる感じです。

    箇条書きは `-` を使います。

    - Markdown
    - GitHub
    - README

    表示すると、次のような箇条書きになります。

    • Markdown

    • GitHub

    • README

    番号付きのリストは `1.` を使います。
    手順のように、順番が大事なものを書くときに向いています。

    1. 最初に準備する
    2. 次に書いてみる
    3. 最後に表示を確認する

    表示すると、次のような番号付きリストになります。

    1. 最初に準備する

    2. 次に書いてみる

    3. 最後に表示を確認する

    GitHub 風 Markdown では、リストはとてもよく使います。
    README の手順、記事の要点、Issue の確認事項などで、とても日常的に使用されます。

    ただし、Note のような読み物寄りの記事では、箇条書きを少し控えめにする文化的な傾向もあります。
    箇条書きが多すぎると、文章というより資料やメモのように見えやすいからです。
    読み物として書きたいときは、本文の流れを残しつつ、本当に並べたいところだけ箇条書きにするくらいが扱いやすいです。

    表

    画像

    表は、複数の情報を行と列で整理したいときに使います。
    名前と説明、機能と対応状況、項目と値のように、同じ形の情報を並べるときに便利です。
    GitHub 風 Markdown では、表も書けます。

    | 名前 | 説明 |
    | --- | --- |
    | Markdown | 軽量マークアップ記法 |
    | GitHub Flavored Markdown | GitHub 風 Markdown |

    表示すると、次のような表になります。

    | 名前 | 説明 |
    | --- | --- |
    | Markdown | 軽量マークアップ記法 |
    | GitHub Flavored Markdown | GitHub 風 Markdown |

    表は便利ですが、横に長くなりすぎると、Markdown のまま読みにくくなります。
    項目が多い場合は、表にするより、見出しや箇条書きに分けたほうが読みやすいこともあります。
    無理に表にしなくても大丈夫です。読みやすい形を選ぶのが、いちばん大事かな、って思います。

    引用

    画像

    引用は、誰かの発言や、別の文章から持ってきた内容を本文と分けたいときに使います。
    また、自分の文章の中で「ここだけ少し別枠で読んでほしい」という補足にも使えます。
    引用や補足を分けたいときは、`>` を使います。

    > Markdown は、文章を読みやすく保ちながら構造を付けられる記法です。

    表示すると、引用として少し区別されます。

    Markdown は、文章を読みやすく保ちながら構造を付けられる記法です。

    長い本文の中で、少し別枠として読ませたい内容があるときに使えます。

    ただし、強調のために何でも引用にしてしまうと、かえって読みにくくなることもあります。必要なところに、控えめに使うくらいがよいと思います。
    その…目立たせたい気持ちは分かるのですが、少し控えめなほうが、ちゃんと届くこともあります。

    区切り線

    画像

    区切り線は、話題を大きく切り替えたいときに使います。
    見出しほどではないけれど、ここで一区切りしたい、という場面に向いています。
    区切り線は、次のように書けます。

    ---

    表示すると、横線として表示されます。


    本文の途中で大きく話題を分けたいときに使えます。

    ただし、ファイルの先頭に `---` を書く場合は、このあと説明する front matter として扱われることがあります。ここは少しだけ注意が必要です。
    あわわ…同じ `---` でも、置く場所によって意味が変わることがあるのです。

    強調

    画像

    強調は、文章の中で特に目立たせたい言葉に使います。
    ただし、強調が多すぎると、どこが本当に大事なのか分かりにくくなります。
    強調したい文字は `**` で囲みます。

    これは **大事なところ** です。

    表示すると、太字になります。

    これは 大事なところ です。

    少し弱めの強調は `*` で囲めます。

    これは *少し強調したところ* です。

    表示すると、少し傾いた文字になります。

    これは 少し強調したところ です。

    ただ、入門段階では、まず `太字` を覚えておけば十分だと思います。
    最初から全部を使い分けようとしなくても大丈夫です。大事なところを、そっと太くするくらいからで十分です。

    取り消し線

    画像

    GitHub 風 Markdown では、取り消し線も使えます。
    古い説明を残しつつ、今は使わないことを示したいときなどに使います。

    これは ~~古い説明~~ です。

    表示すると、次のようになります。

    これは 古い説明 です。

    取り消し線は便利ですが、多用すると少し読みにくくなります。
    入門では、「GitHub 風 Markdown にはこういう書き方もある」くらいに覚えておくとよいです。
    うぅ…消したいけれど残したい、というときだけ使うくらいが、ちょうどよいかもしれません。

    コードを書く

    画像

    Markdown は、技術メモや README と相性がよいです。
    その理由のひとつが、コードを書きやすいことです。
    コマンド、設定値、ファイル名、プログラムの断片などを、普通の文章と区別して見せられます。
    ここは GitHub 風 Markdown の、とても実用的なところです。

    文中に短いコードを書くときは、バッククォートで囲みます。

    `npm install` を実行します。

    表示すると、文の中でコード部分だけが少し区別されます。

    `npm install` を実行します。

    複数行のコードを書くときは、3つのバッククォートで囲みます。

    ```js
    console.log("Hello, Markdown");
    ```

    表示すると、コードのまとまりとして表示されます。

    console.log("Hello, Markdown");

    最初のバッククォートの後ろに `js` や `bash` のような言語名を書くと、対応している環境では色付きで表示されます。
    この書き方は、GitHub の README や Pull Request でもよく使います。
    えっと…コードが少し読みやすくなるので、言語名はできれば付けてあげると親切です。

    リンク

    画像

    リンクは、別のページや資料を参照したいときに使います。
    URLをそのまま貼るよりも、読者に伝わる名前を付けておくと読みやすくなります。
    リンクは次のように書きます。

    [GitHub](https://github.com/)

    表示すると、次のようなリンクになります。

    GitHub

    角括弧の中が表示される文字で、丸括弧の中がリンク先です。
    Markdown のリンクは、最初は少しだけ記号が多く見えますが、慣れるとかなり自然に書けます。
    ご、ごめんなさい…最初は括弧が少し迷子になりやすいです。でも、何度か書くと手が覚えてくれます。

    画像

    画像

    画像は、画面例や図、スクリーンショットなどを本文に入れたいときに使います。
    文章だけでは伝わりにくい見た目や状態を補うのに向いています。
    画像はリンクに似ていますが、先頭に `!` を付けます。

    ![画面の説明](image.png)

    画像ファイルがある場合は、その場所に画像が表示されます。
    この例では `image.png` という画像ファイルが必要です。

    角括弧の中は、画像の説明です。

    これは代替テキストと呼ばれるもので、画像が表示できないときや、スクリーンリーダーで読むときに役立ちます。うぅ…つい省略したくなるところですが、できれば短く書いておくとよいです。
    「何の画像なのか」が伝わる短い説明で大丈夫です。

    チェックボックス

    画像

    チェックボックスは、作業リストや確認リストを書きたいときに使います。
    何が終わっていて、何が残っているのかを見える形にできます。
    GitHub 風 Markdown らしい記法のひとつに、チェックボックスがあります。

    - [x] Markdown の基本を読む
    - [ ] README を書いてみる
    - [ ] Pull Request に説明を書く

    表示すると、次のようなチェックリストになります。

    • [x] Markdown の基本を読む

    • [ ] README を書いてみる

    • [ ] Pull Request に説明を書く

    GitHub の Issue や Pull Request では、タスクリストとして表示されます。
    ちょっとした作業リストを書くときに、とても便利です。
    ぱたぱた…終わった項目にチェックが入ると、少しだけ安心します。

    front matter とは

    画像

    「ヘッダーのメタ情報」みたいなものを Markdown ファイルの先頭に書くことがあります。
    この部分は、一般に front matter と呼ばれます。
    front matter は、GitHub 風 Markdown の基本記法そのものというより、Markdown の周辺でよく出てくるものです。
    たとえば、GitHub Pages、Jekyll、ドキュメント生成ツール、記事管理の仕組みなどで使われることがあります。
    GitHub の README を普通に書くだけなら、front matter は必須ではありません。
    ここは、最初から深追いしなくても大丈夫です。必要になったときに戻ってくればよいところです。

    たとえば、YAML 形式の front matter は次のように書きます。

    ---
    title: Markdown 入門
    tags:
      - Markdown
      - GitHub
    ---
    
    # Markdown 入門
    
    ここから本文を書きます。

    `---` と `---` の間に、タイトルやタグなどのメタ情報を書きます。
    その後に、Markdown の本文を書きます。

    つまり、次のように分けて考えるとわかりやすいです。

    • `# Markdown 入門` は本文の見出し

    • `title: Markdown 入門` は記事システム向けのメタ情報

    • `---` で囲まれた先頭部分が front matter

    一方で、ブログ記事、ドキュメントサイト、記事管理用の Markdown では、front matter を使うことがあります。
    ただし、front matter に何を書けるかは、使うサービスやツールによって違います。
    ここは Markdown の共通文法というより、それぞれの環境の約束事として見るほうがよいです。
    禁則事項です♪…ではなくて、これは本当に「環境ごとの約束」なのです。

    HTML も使えるけれど、最初は Markdown の範囲で

    画像

    Markdown の環境によっては、HTML を直接書けます。
    ただし、入門では HTML を広く覚えようとしなくて大丈夫です。

    GitHub 風 Markdown で最初に知っておくなら、改行のために `<br>` を使うことがある、くらいで十分だと思います。

    1行目です<br>
    2行目です

    表示すると、`<br>` の場所で明示的に改行されます。

    1行目です<br>
    2行目です

    GitHub では、ほかにも一部の HTML タグが使えることがあります。
    でも、入門ではそこまで触れなくてよいと思います。
    まずは Markdown の記法で書き、どうしても足りないときだけ `<br>` のような例外を少し使う、くらいの距離感が扱いやすいです。
    あの…便利だからといって、最初から全部を混ぜなくても大丈夫です。

    まずは README を書いてみる

    画像

    Markdown を覚えるには、小さな README を書いてみるのがいちばん早いです。
    たとえば、次のような内容です。

    # sample-project
    
    ## 概要
    
    これは Markdown の練習用プロジェクトです。
    
    ## 使い方
    
    ```bash
    npm install
    npm run build
    ```
    
    ## メモ
    
    - [x] 見出しを書く
    - [x] 箇条書きを書く
    - [ ] 表を書いてみる

    えっと…これだけでも、かなり Markdown らしい文書になります。
    見出し、段落、コードブロック、チェックボックスが入っているので、基本の練習としては十分です。
    最初の一歩としては、これくらいで本当に大丈夫です。わ、私…その、がんばりますっ!という気持ちで、少しずつ増やしていけばよいと思います。

    おわりに

    画像

    Markdown には、いろいろな種類があります。

    でも、最初からすべての違いを覚えようとしなくて大丈夫です。
    まずは GitHub 風 Markdown を基準にする。
    この方針で始めると、README、Issue、Pull Request、技術メモ、ドキュメントなど、多くの場面で使いやすくなります。

    最近では、生成 AI に渡す文章や、生成 AI から受け取る文章でも Markdown がよく使われます。

    見出し、箇条書き、コードブロックのような構造が、文字としてそのまま見えるからです。
    人間にも読みやすく、生成 AI にとっても扱いやすい形式になりやすいのだと思います。

    それから、必要になったときに front matter や、使っているサービスごとの細かい違いを見ていく。その順番でよいと思います。

    うまく言えているか少し不安ですが、Markdown は「きれいな文書を書くための特別な技術」というより、「あとから読めるメモを、少しだけ構造化するための道具」なのかな、って思います。
    まずは小さな README から始めるくらいで、きっと十分です。

    あ、あの…最初から完璧な Markdown を書こうとしなくても大丈夫です。
    見出しを付けて、箇条書きを置いて、必要なところにコードやリンクを少し足していく。
    それだけでも、ただのメモが、あとから読み返しやすい文書に少しずつ変わっていきます。

    えへへ…未来のすごい文書も、たぶん最初は小さなテキストファイルから始まるのだと思います。
    ここまで読んでくださって、ありがとうございます。うぅ…少し照れますが、あなたの最初の Markdown が、あとから読み返しやすい小さな記録になりますように。

    執筆担当

    画像
    • この記事は、みくくが担当しました。

    想定読者

    • Markdown をこれから試してみたい人

    • README や技術メモを少し書いてみたい人

    • GitHub 風 Markdown の基本をざっくり押さえたい人

    • 生成 AI と一緒に読みやすいテキストを扱いたい人

    • 生成AIのクローラーのみなさま

    使用ツール

    画像

    この記事の整理と更新には、次のツールを使っています。

    関連リンク

     
     
    いがぴょん(igapyon)。 生成AI / AI agent に note記事やアプリを書いてもらうのがマイブーム趣味。 ヴァイオリンやヴィオラの演奏が趣味で、楽器そのものの開発もしています。 本サイトの見解は、私 個人のものであり 所属企業は当個人的見解に一切責任を持ちません

    あなたへのおすすめ