Markdown拡張機能

元のテキスト

https://github.com/vuejs/vitepress/blob/3c40e9d9a8443433f49599111ee571d569de530d/docs/en/guide/markdown.md

VitePressには、ビルトインのMarkdown拡張機能が含まれています。

見出しアンカー

見出しには自動的にアンカーリンクが適用されます。アンカーのレンダリングはmarkdown.anchorオプションで設定できます。

カスタムアンカー

自動生成されたアンカーの代わりにカスタムアンカータグを指定するには、見出しにサフィックスを追加します。

# カスタムアンカーを使用する {#my-anchor}

これにより、デフォルトの#using-custom-anchorsではなく、#my-anchorとしてリンクできるようになります。

リンク

内部リンクと外部リンクの両方に特別な処理が行われます。

内部リンク

内部リンクはSPAナビゲーションのためにルータリンクに変換されます。また、各サブディレクトリに含まれるすべてのindex.mdは自動的にindex.htmlに変換され、対応するURL/でアクセスできます。

例えば、次のディレクトリ構造があるとします。

.
├─ index.md
├─ foo
│  ├─ index.md
│  ├─ one.md
│  └─ two.md
└─ bar
   ├─ index.md
   ├─ three.md
   └─ four.md

そして、foo/one.mdにいると仮定します。

[Home](/) <!-- ルートのindex.mdにユーザーを送ります -->
[foo](/foo/) <!-- fooディレクトリのindex.htmlにユーザーを送ります -->
[foo heading](./#heading) <!-- fooのindexファイル内の見出しにアンカーを設定 -->
[bar - three](../bar/three) <!-- 拡張子を省略できます -->
[bar - three](../bar/three.md) <!-- .mdを追加できます -->
[bar - four](../bar/four.html) <!-- .htmlを追加できます -->

ページサフィックス

ページと内部リンクは、デフォルトで.htmlサフィックスが付いた状態で生成されます。

外部リンク

外部リンクには自動的にtarget="_blank" rel="noreferrer"が追加されます。

フロントマター

YAMLフロントマターは、最初からサポートされています。

yaml

---
title: ハッカーのようにブログを書く
lang: en-US
---

このデータは、カスタムコンポーネントやテーマコンポーネントとともにページ全体で利用できます。

詳細はフロントマターを参照してください。

GitHubスタイルのテーブル

入力

| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |

出力

Tables	Are	Cool
col 3 is	right-aligned	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

絵文字 🎉

入力

:tada: :100:

出力

🎉 💯

すべての絵文字リストが利用可能です。

カスタムコンテナ

カスタムコンテナは、そのタイプ、タイトル、コンテンツによって定義できます。

デフォルトタイトル

入力

::: info
これはインフォボックスです。
:::

::: tip
これはティップです。
:::

::: warning
これは警告です。
:::

::: danger
これは危険な警告です。
:::

::: details
これは詳細ブロックです。
:::

出力

INFO

これはインフォボックスです。

TIP

これはティップです。

WARNING

これは警告です。

DANGER

これは危険な警告です。

Details

これは詳細ブロックです。

カスタムタイトル

カスタムタイトルを設定するには、コンテナの「タイプ」のすぐ後にテキストを追加します。

入力

::: danger 停止
危険区域、進まないでください
:::

::: details クリックしてコードを表示
```js
console.log('Hello, VitePress!')
```
:::

出力

停止

危険区域、進まないでください

クリックしてコードを表示

console.log('Hello, VitePress!')

また、グローバルにカスタムタイトルを設定することもできます。英語以外で書いている場合に便利です。

// config.ts
export default defineConfig({
  // ...
  markdown: {
    container: {
      tipLabel: '提示',
      warningLabel: '警告',
      dangerLabel: '危险',
      infoLabel: '信息',
      detailsLabel: '详细信息'
    }
  }
  // ...
})

`raw`

これは、VitePressとのスタイルやルータの競合を防ぐために使用できる特別なコンテナです。特にコンポーネントライブラリをドキュメント化している場合に便利です。より良い分離のためには、whyframeもチェックすることをお勧めします。

構文

::: raw
<div class="vp-raw">
:::

vp-rawクラスは、要素に直接使用することもできます。スタイルの分離は現在オプトインです。

お好みのパッケージマネージャーでpostcssをインストールします。
sh
```
$ npm add -D postcss
```
docs/postcss.config.mjsというファイルを作成し、次の内容を追加します。
js
```
import { postcssIsolateStyles } from 'vitepress'

export default {
  plugins: [postcssIsolateStyles()]
}
```
これは、内部でpostcss-prefix-selectorを使用しています。次のようにオプションを渡すことができます。
js
```
postcssIsolateStyles({
  includeFiles: [/vp-doc\.css/] // デフォルトは /base\.css/
})
```

GitHub風のアラート

VitePressは、コールアウトとしてレンダリングするGitHub風のアラートもサポートしています。これらはカスタムコンテナと同じようにレンダリングされます。

> [!NOTE]
> ユーザーが読み飛ばしても考慮すべき情報を強調します。

> [!TIP]
> ユーザーがより成功するためのオプション情報を提供します。

> [!IMPORTANT]
> ユーザーが成功するために必要な重要な情報です。

> [!WARNING]
> 潜在的なリスクがあるため、ユーザーの即時の注意を必要とする重要な内容です。

> [!CAUTION]
> 行動の負の潜在的結果について警告します。

NOTE

ユーザーが読み飛ばしても考慮すべき情報を強調します。

TIP

ユーザーがより成功するためのオプション情報を提供します。

IMPORTANT

ユーザーが成功するために必要な重要な情報です。

WARNING

潜在的なリスクがあるため、ユーザーの即時の注意を必要とする重要な

内容です。

CAUTION

行動の負の潜在的結果について警告します。

コードブロックのシンタックスハイライト

VitePressは、Shikiを使用して、Markdownコードブロック内の言語構文を色付きテキストでハイライトします。Shikiはさまざまなプログラミング言語をサポートしています。コードブロックの開始バックティックに有効な言語エイリアスを追加するだけです。

入力

```js
export default {
  name: 'MyComponent',
  // ...
}
```

```html
<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>
```

出力

export default {
  name: 'MyComponent'
  // ...
}

html

<ul>
  <li v-for="todo in todos" :key="todo.id">
    {{ todo.text }}
  </li>
</ul>

有効な言語のリストはShikiのリポジトリで確認できます。

アプリの設定でシンタックスハイライトテーマをカスタマイズすることもできます。詳細はmarkdownオプションを参照してください。

コードブロックの行ハイライト

入力

```js{4}
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

出力

export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}

単一の行だけでなく、複数の単一行、範囲、またはその両方を指定することもできます。

行の範囲：例えば{5-8}、{3-10}、{10-17}
複数の単一行：例えば{4,7,9}
行の範囲と単一行：例えば{4,7-13,16,23-27,40}

入力

```js{1,4,6-8}
export default { // ハイライトされた行
  data () {
    return {
      msg: `Highlighted!
      この行はハイライトされていませんが、
      これと次の2行はハイライトされています。`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}
```

出力

export default { // ハイライトされた行
  data () {
    return {
      msg: `Highlighted!
      この行はハイライトされていませんが、
      これと次の2行はハイライトされています。`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum',
    }
  }
}

また、// [!code highlight]コメントを使用して行内で直接ハイライトすることもできます。

入力

```js
export default {
  data () {
    return {
      msg: 'Highlighted!' // [!!code highlight]
    }
  }
}
```

出力

export default {
  data() {
    return {
      msg: 'Highlighted!'
    }
  }
}

コードブロックのフォーカス

行に// [!code focus]コメントを追加すると、その行がフォーカスされ、他の部分がぼやけます。

また、// [!code focus:<行数>]を使用して、フォーカスする行数を定義することもできます。

入力

```js
export default {
  data () {
    return {
      msg: 'Focused!' // [!!code focus]
    }
  }
}
```

出力

export default {
  data() {
    return {
      msg: 'Focused!'
    }
  }
}

コードブロックのカラードディフ

行に// [!code --]または// [!code ++]コメントを追加すると、その行のディフが作成され、コードブロックの色が保持されます。

入力

```js
export default {
  data () {
    return {
      msg: 'Removed' // [!!code --]
      msg: 'Added' // [!!code ++]
    }
  }
}
```

出力

export default {
  data () {
    return {
      msg: 'Removed'
      msg: 'Added'
    }
  }
}

コードブロックのエラーと警告

行に// [!code warning]または// [!code error]コメントを追加すると、それに応じた色で表示されます。

入力

```js
export default {
  data () {
    return {
      msg: 'Error', // [!!code error]
      msg: 'Warning' // [!!code warning]
    }
  }
}
```

出力

export default {
  data() {
    return {
      msg: 'Error', 
      msg: 'Warning'
    }
  }
}

行番号

コードブロックごとに行番号を有効にするには、設定を行います。

export default {
  markdown: {
    lineNumbers: true
  }
}

詳細はmarkdownオプションを参照してください。

フェンス付きコードブロックに:line-numbersまたは:no-line-numbersマークを追加して、設定された値を上書きできます。

行番号の開始位置をカスタマイズすることもできます。例えば、:line-numbers=2とすると、コードブロックの行番号が2から始まります。

入力

```ts {1}
// デフォルトで行番号は無効です
const line2 = 'これは2行目です'
const line3 = 'これは3行目です'
```

```ts:line-numbers {1}
// 行番号が有効です
const line2 = 'これは2行目です'
const line3 = 'これは3行目です'
```

```ts:line-numbers=2 {1}
// 行番号が有効で2から開始します
const line3 = 'これは3行目です'
const line4 = 'これは4行目です'
```

出力

// デフォルトで行番号は無効です
const line2 = 'これは2行目です'
const line3 = 'これは3行目です'

// 行番号が有効です
const line2 = 'これは2行目です'
const line3 = 'これは3行目です'

// 行番号が有効で2から開始します
const line3 = 'これは3行目です'
const line4 = 'これは4行目です'

コードスニペットのインポート

既存のファイルからコードスニペットをインポートできます。

<<< @/filepath

行ハイライトもサポートしています。

<<< @/filepath{highlightLines}

入力

<<< @/snippets/snippet.js{2}

コードファイル

出力

TIP

@の値はソースルートに対応します。デフォルトではVitePressプロジェクトのルートですが、srcDirが設定されている場合は異なります。また、相対パスからもインポートできます。

<<< ../snippets/snippet.js

VS Codeのリージョンを使用して、コードファイルの対応する部分のみを含めることもできます。ファイルパスの後に#を付けてカスタムリージョン名を指定できます。

入力

<<< @/snippets/snippet-with-region.js#snippet{1}

コードファイル

出力

中括弧内に言語を指定することもできます。

<<< @/snippets/snippet.cs{c#}

<!-- 行のハイライト付き: -->

<<< @/snippets/snippet.cs{1,2,4-6 c#}

<!-- 行番号付き: -->

<<< @/

snippets/snippet.cs{1,2,4-6 c#:line-numbers}

ファイル拡張子からソース言語が推測できない場合に便利です。

コードグループ

複数のコードブロックをグループ化できます。

入力

::: code-group

```js [config.js]
/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config
```

```ts [config.ts]
import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config
```

:::

出力

config.jsconfig.ts

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  // ...
}

export default config

import type { UserConfig } from 'vitepress'

const config: UserConfig = {
  // ...
}

export default config

コードグループ内でスニペットをインポートすることもできます。

入力

::: code-group

<!-- ファイル名はデフォルトでタイトルとして使用されます -->

<<< @/snippets/snippet.js

<!-- カスタムタイトルも指定できます -->

<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [リージョンスニペット]

:::

出力

Markdownファイルのインクルード

Markdownファイルを別のMarkdownファイルにインクルードできます。ネストも可能です。

TIP

Markdownパスの前に@を付けることもできます。これにより、ソースルートとして機能します。デフォルトではVitePressプロジェクトのルートですが、srcDirが設定されている場合は異なります。

例えば、次のようにして相対的なMarkdownファイルをインクルードできます。

入力

# ドキュメント

## 基本

<!--@include: ./parts/basics.md-->

パートファイル（parts/basics.md）

基本的な入門内容。

### 設定

`.foorc.json`を使用して作成できます。

同等のコード

# ドキュメント

## 基本

基本的な入門内容。

### 設定

`.foorc.json`を使用して作成できます。

行範囲を選択することもできます。

入力

# ドキュメント

## 基本

<!--@include: ./parts/basics.md{3,}-->

パートファイル（parts/basics.md）

基本的な入門内容。

### 設定

`.foorc.json`を使用して作成できます。

同等のコード

# ドキュメント

## 基本

### 設定

`.foorc.json`を使用して作成できます。

選択する行範囲の形式は次のとおりです：{3,}、{,10}、{1,10}

入力

# ドキュメント

## 基本

<!--@include: ./parts/basics.md#basic-usage{,2}-->
<!--@include: ./parts/basics.md#basic-usage{5,}-->

パートファイル（parts/basics.md）

<!-- #region basic-usage -->
## 使用法ライン1

## 使用法ライン2

## 使用法ライン3
<!-- #endregion basic-usage -->

同等のコード

# ドキュメント

## 基本

## 使用法ライン1

## 使用法ライン3

WARNING

ファイルが存在しない場合でもエラーは発生しません。この機能を使用する際は、内容が期待通りにレンダリングされていることを確認してください。

数式

現在、この機能はオプトインです。これを有効にするには、markdown-it-mathjax3をインストールし、設定ファイルでmarkdown.mathをtrueに設定する必要があります。

npm add -D markdown-it-mathjax3

// .vitepress/config.ts
export default {
  markdown: {
    math: true
  }
}

入力

$a \ne 0$のとき、$(ax^2 + bx + c = 0)$には2つの解があり、それらは
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$
です。

**マクスウェルの方程式：**

| equation                                                                                                                                                                  | description                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | $\vec{\mathbf{B}}$の発散はゼロ                                                          |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | $\vec{\mathbf{E}}$のカールは$\vec{\mathbf{B}}$の変化率に比例する                        |
| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_                                                                                 |

出力

$a \ne 0$のとき、$(ax^2 + bx + c = 0)$には2つの解があり、それらは $$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$ です。

マクスウェルの方程式：

equation	description
$\nabla \cdot \vec{\mathbf{B}} = 0$	$\vec{\mathbf{B}}$の発散はゼロ
$\nabla \times \vec{\mathbf{E}}, +, \frac1c, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$	$\vec{\mathbf{E}}$のカールは$\vec{\mathbf{B}}$の変化率に比例する
$\nabla \times \vec{\mathbf{B}} -, \frac1c, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$	wha?

画像の遅延読み込み

設定ファイルでlazyLoadingをtrueに設定すると、Markdown経由で追加された各画像に対して遅延読み込みを有効にできます。

export default {
  markdown: {
    image: {
      // 画像の遅延読み込みはデフォルトで無効です
      lazyLoading: true
    }
  }
}

高度な設定

VitePressは、Markdownレンダラーとしてmarkdown-itを使用しています。上記の多くの拡張機能はカスタムプラグインを通じて実装されています。.vitepress/config.jsでmarkdownオプションを使用して、markdown-itインスタンスをさらにカスタマイズできます。

import { defineConfig } from 'vitepress'
import markdownItAnchor from 'markdown-it-anchor'
import markdownItFoo from 'markdown-it-foo'

export default defineConfig({
  markdown: {
    // markdown-it-anchorのオプション
    // https://github.com/valeriangalliat/markdown-it-anchor#usage
    anchor: {
      permalink: markdownItAnchor.permalink.headerLink()
    },

    // @mdit-vue/plugin-tocのオプション
    // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
    toc: { level: [1, 2] },

    config: (

md) => {
      // さらに多くのmarkdown-itプラグインを使用
      md.use(markdownItFoo)
    }
  }
})

設定可能なプロパティの完全なリストについては、設定リファレンス：アプリ設定を参照してください。

Markdown拡張機能 ​

見出しアンカー ​

カスタムアンカー ​

リンク ​

内部リンク ​

ページサフィックス ​

外部リンク ​

フロントマター ​

GitHubスタイルのテーブル ​

絵文字 🎉 ​

目次 ​

カスタムコンテナ ​

デフォルトタイトル ​

カスタムタイトル ​

raw ​

GitHub風のアラート ​

コードブロックのシンタックスハイライト ​

コードブロックの行ハイライト ​

コードブロックのフォーカス ​

コードブロックのカラードディフ ​

コードブロックのエラーと警告 ​

行番号 ​

コードスニペットのインポート ​

コードグループ ​

Markdownファイルのインクルード ​

数式 ​

画像の遅延読み込み ​

高度な設定 ​

Markdown拡張機能

見出しアンカー

カスタムアンカー

リンク

内部リンク

ページサフィックス

外部リンク

フロントマター

GitHubスタイルのテーブル

絵文字 🎉

目次

カスタムコンテナ

デフォルトタイトル

カスタムタイトル

`raw`

GitHub風のアラート

コードブロックのシンタックスハイライト

コードブロックの行ハイライト

コードブロックのフォーカス

コードブロックのカラードディフ

コードブロックのエラーと警告

行番号

コードスニペットのインポート

コードグループ

Markdownファイルのインクルード

数式

画像の遅延読み込み

高度な設定