NKSSG
NakaKen Static Site Generator
Home / ガイド / Appendix / Markdown

Markdown

Markdown

Markdown とは、文書を書くためのフォーマットの1つです。HTML に変換することを想定していますが、HTML よりも書きやすいため、人気があります。

ここでは、Markdown での記事の書き方を説明していきます。

なお、NKSSG では、Markdown から HTML へ変換するための処理に Python-Markdown というパッケージを使っています。以下の説明は、このパッケージを使う前提の説明です。

【目次】

Markdownについての注意

いきなりですが、Markdown について注意点があります。

Markdown には、方言があります。

もともと、Markdown は「HTML より簡単に書けて、 HTML に変換できるフォーマット」として使われてきましたが、HTML のすべての機能に対応しているわけではありません。そのため、多くのシステムやサービスでは、おおもとの Markdown の仕様に独自の拡張を追加しています。

そのため、もしあなたがすでに Markdown で記事を書いたことがあったとしても、別のサービスでは同じように書けないかもしれません。

NKSSG では Markdown に対して独自の拡張機能は用意していません。Python-Markdown に拡張機能を追加する形で使うことを想定しています。

基本的なMarkdown記法

以下では、Python-Markdown でデフォルトの状態で使えるものを中心に、Markdown 記法の説明をしていきます。

段落と改行

文章を空行で分けると、段落として扱われます。

【変換前】
文章1

文章2

【変換後】
<p>文章1</p>
<p>文章2</p>

なお、改行をしただけでは、改行は反映されません。改行の後に半角スペースを2個入れると、改行が反映されます。

【変換前】
文1
文2

文3  
文4（文3の後には、半角スペースが2個入っている）

【変換後】
<p>文1
文2</p>
<p>文3<br/>
文4（文3の後には、半角スペースが2個入っている）</p>

見出し

#(シャープ)を使って、見出しを書くことができます。# の数が、見出しのレベルと対応します。# と文字の間には、半角スペースが必要です。

【変換前】
# h1
## h2
### h3
#### h4
##### h5
###### h6

【変換後】
<h1>h1</h1>
<h2>h2</h2>
<h3>h3</h3>
<h4>h4</h4>
<h5>h5</h5>
<h6>h6</h6>

箇条書きリスト

半角のハイフン、プラス、アスタリスクを使うと、箇条書きリストを書くことができます。記号は3つのうちどれを使っても構いません。記号と文字の間には、半角スペースが必要です。

【変換前】
- list 1
    - list 1-1
        - list 1-1-1
    - list 1-2
- list 2
- list 3

【変換後】
<ul>
  <li>list 1<ul>
    <li>list 1-1<ul>
      <li>list 1-1-1</li>
      </ul>
    </li>
    <li>list 1-2</li>
    </ul>
  </li>
  <li>list 2</li>
  <li>list 3</li>
</ul>

半角4文字のインデントを入れると、入れ子にすることもできます。（わかりやすいように変換後にはインデントを追加しました）

番号付きリスト

数値と半角ドットを使うと、番号付き書きリストを書くことができます。数値は何でもいいので、「1. 文字」と書いておけばいいです。

ドットと文字の間には、半角スペースが必要です。

【変換前】
1. list 1
    1. list 1-1
        1. list 1-1-1
    1. list 1-2
1. list 2
1. list 3

【変換後】
<ol>
  <li>list 1<ol>
    <li>list 1-1<ol>
      <li>list 1-1-1</li>
      </ol>
    </li>
    <li>list 1-2</li>
    </ol>
  </li>
  <li>list 2</li>
  <li>list 3</li>
</ol>

半角4文字のインデントを入れると、入れ子にすることもできます。（わかりやすいように変換後にはインデントを追加しました）

引用

半角の > で、引用を表すことができます。記号と文字の間には半角スペースが必要です。

【変換前】
> This is blockquote.

【変換後】
<blockquote>
<p>This is blockquote.</p>
</blockquote>

引用の中に、さらに引用を含めたい場合は、 >> と2個続けて書きます。また、他の要素（リストなど）を引用の中に入れることもできます。

コードブロック

コードブロックを追加するには、半角4文字でインデントをつけます。

【変換前】
    int i = 0;

【変換後】
<pre><code>int i = 0;
</code></pre>

他の書き方として、コードブロックを「バッククォート3つで囲む」方法も、一般的によく使われます。

【変換前】
```
int i = 0;
```

実は、この書き方は本来の Markdown の仕様には入っていません。Python-Markdown でも、デフォルトの状態では使えません。しかし、後述する拡張機能を使って、次のようにnkssg.ymlファイル内で拡張機能の設定を行えば、使うことができます。

markdown:
  - fenced_code

なお、NKSSG のインストール直後は、この設定が追加されているので、「バッククォート3つで囲む」書き方も使えます。この設定を消すと使えなくなります。

水平線

半角のハイフン、アスタリスク、アンダースコアを3個以上書くと、hrタグに変換されます。

【変換前】
---

【変換後】
<hr/>

リンク

リンクしたいテキストを半角の角カッコで囲み、リンク先の URL を半角の丸カッコで囲むと、リンクを表すことができます。

【変換前】
[sample](http://example.com)

【変換後】
<a href="http://example.com">sample</a>

target などの設定はできません。

画像

画像は、半角のエクスクラメーションマークをつけて、リンクと同じように書きます。どのように変換されるかは、サンプルを見るとわかるでしょう。

【変換前】
![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

【変換後】
<img alt="Alt text" src="/path/to/img.jpg"/>
<img alt="Alt text" src="/path/to/img.jpg" title="Optional title"/>

角カッコがaltに、丸カッコに書いたパスがsrcに反映されます。パスのあとに半角スペースをあけて文字を追加すると、titleを設定することができます。

強調

半角のアスタリスクやアンダースコアで文字を囲むと、emタグに変換されます。2個で囲むとstrongタグに、3個で囲むとこの2つで囲まれるように変換されます。

【変換前】
*em*
**strong**
***em + strong***

【変換後】
<em>em</em>
<strong>strong</strong>
<strong><em>em + strong</em></strong>

VSCodeでは、テキストを選択した状態で半角のアスタリスクやアンダースコアを入力すると、テキストの前後を囲ってくれます。

コード

文章中にコードを入れたい場合は、バッククォートで囲みます。

【変換前】
This is `code` tag.

【変換後】
This is <code>code</code> tag.

コードブロックは拡張機能を使わないといけませんでしたが、このコードはデフォルトの機能に含まれています。

公式の拡張機能

Python-Markdown には、公式にサポートしている拡張機能があります。公式サポートの拡張機能の一覧はこちら にありますが、以下ではその中でよく使いそうなものと、それを NKSSG でどう使うかを説明していきます。

コードブロック

コードブロックのところでも書きましたが、本来、Markdown でコードブロックを書くには、行頭に半角スペース4つが必要です。しかし、Fenced Code Blocks という拡張機能を使えば、バックスラッシュ3つで囲むことで、コードブロックを表現することができるようになります。リンク先には、言語やクラス、ID を指定する方法も載っているので、確認してみましょう。

この機能を NKSSG で使うためには、nkssg.ymlで次のように設定します。

markdown: 
  - fenced_code

デフォルトではこの拡張機能は有効になっています。

目次

本文中に目次を追加することができます。Table of Contents という拡張機能を使います。NKSSG では、次のようにnkssg.ymlで設定されているので、デフォルトの状態で使えるようになっています。

markdown:
  - toc:
      marker: "[toc]"

この拡張機能には、値を設定することができます。拡張機能に何かを設定する場合は、上のように書きます。拡張名tocの後にコロンをつけ、次の行にインデントをつけて「設定項目: 値」とします。上の例であれば、[toc]と書いたところが目次に代わる、という設定をしていることになります。

Table of Contents の下の方に、設定できる項目が記載されています。

他の拡張機能を使うには

拡張機能の一覧 には、他にもたくさんの拡張機能がサポートされています。この中から使いたいものがあれば、次のように設定しましょう（上2つの例を見ればわかると思いますが）。

nkssg.ymlの中で、次の場所を探します。

markdown:

この次の行に、拡張機能の名前をリスト形式で追加していきます。拡張機能のページの一番下にある Usage のところに、拡張機能の名前が載っているので、次のようにします。

markdown:
  - {ext-name}

もし、拡張機能に設定項目があって、何か値を設定したい場合は次のようにします。

markdown:
  - {ext-name}:
      {setting-name1}: {value1}
      {setting-name2}: {value2}

{ext-name}の後にコロンがいること、設定項目はインデントをつけることに注意しましょう。

その他のこまごましたこと

上で紹介した Markdown 記法の一覧には、table がありません。実は、table も本来の仕様には含まれていません。table を使いたい場合は、次のようにnkssg.ymlで設定する必要があります。

markdown:
  - tables

Markdown でどのように書くかは、Tables を参考にしてください。

拡張機能の中で、属性を追加できる機能があります。

markdown:
  - attr_list

これを使うと、例えば次のような使い方ができます。「#」 で始めれば id に、「.」で始めれば class になります。

【変換前】
# h1 { #main-title .header }

[with target](http://example.com){ target=_blank rel="noopener noreferrer" }

![](http://example.com/sample.png){ lazy=loading width=300 }


【変換後】
<h1 class="header" id="main-title">h1</h1>

<p><a href="http://example.com" rel="noopener noreferrer" target="_blank">with target</a></p>

<p><img alt="" lazy="loading" src="http://example.com/sample.png" width="300"/></p>

波かっこの中が追加されます。このようにして、id や class を追加したり、リンクを別タブで開くようにしたリ Lazy loading を実現することができます。

サードパーティーの拡張機能

Python-Markdown というパッケージには、外部の拡張機能を使う機能があります。ここでは、そのようなサードパーティーの拡張機能を使う方法について見ていきます。

例として、PyMdown Extensions という拡張機能を見ていきます。

インストール

NKSSG をインストールした時点で、Python-Markdown はインストールされていますが、サードパーティーの拡張機能を使いたい場合は、個別にインストールする必要があります。インストールの方法は、拡張機能によってバラバラですが、今考えている例では次のように行います。

pip install pymdown-extensions

仮想環境をアクティベートしている場合は、仮想環境にインストールされます。

設定

インストールした拡張機能を使うには、NKSSG のnkssg.ymlで設定しないといけません。設定項目は機能によって違いますが、ここでは、MagicLink を使ってみます。この機能には、URL を打ち込んだら、自動的にリンクが設定される、という機能(Auto-Linking) などが含まれています。

設定は次のように行います。MagicLink の上の方に書いてある拡張機能の名前をそのまま入力します。

markdown:
  - pymdownx.magiclink

こうしてから、Markdown ファイル内に、URL を追加してみましょう。URL にリンクが追加されていることがわかります。

このサードパーティーの拡張機能に対しても、設定を行うことができます。リンク先のページの下の方に設定項目の一覧が載っています。例えば、プロトコル(http:// など)を隠すための hide_protocol という設定をしてみます。

markdown:
  - pymdownx.magiclink:
      hide_protocol: True

こうすると、たしかに URL にリンクがついて、しかもテキストからはプロトコルが消えていることがわかります。

おわりに

ここでは、Markdown 形式でのテキストの書き方、そして、拡張機能の設定方法や使い方を見てきました。拡張機能はたくさんあるので、便利なものを取り入れれば、より簡単に NKSSG で記事を書くことができるようになります。

Prev: YAML