Markdown拡張機能

VitePressには、組み込みのMarkdown拡張機能が付属しています。

ヘッダーアンカー

ヘッダーには自動的にアンカーリンクが適用されます。アンカーのレンダリングは、markdown.anchorオプションを使用して構成できます。

カスタムアンカー

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

# Using custom anchors {#my-anchor}

これにより、デフォルトの#using-custom-anchorsの代わりに#my-anchorとして見出しにリンクできます。

リンク

内部リンクと外部リンクの両方が特別に扱われます。

内部リンク

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

たとえば、次のディレクトリ構造が与えられたとします

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

そして、あなたがfoo/one.mdにいるとします

[Home](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extension -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->

ページサフィックス

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

外部リンク

アウトバウンドリンクは自動的にtarget="_blank" rel="noreferrer"になります

フロントマター

YAMLフロントマターがすぐにサポートされています。

yaml

---
title: Blogging Like a Hacker
lang: en-US
---

このデータは、すべてのカスタムコンポーネントおよびテーマコンポーネントとともに、ページの残りの部分で使用できます。

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

GitHubスタイルの表

入力

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

出力

表	は	クール
3列目は	右揃え	$1600
2列目は	中央揃え	$12
縞模様	かっこいい	$1

Emoji 🎉

入力

:tada: :100:

出力

🎉 💯

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

カスタムコンテナ

カスタムコンテナは、タイプ、タイトル、および内容で定義できます。

デフォルトタイトル

入力

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

::: details
This is a details block.
:::

出力

INFO

これは情報ボックスです。

TIP

これはヒントです。

WARNING

これは警告です。

DANGER

これは危険な警告です。

詳細

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

カスタムタイトル

コンテナの「タイプ」の直後にテキストを追加することで、カスタムタイトルを設定できます。

入力

::: danger STOP
Danger zone, do not proceed
:::

::: details Click me to view the code
```js
console.log('Hello, VitePress!')
```
:::

出力

STOP

危険地帯、進まないでください

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

console.log('Hello, VitePress!')

また、英語で記述しない場合は、サイト構成に次のコンテンツを追加することで、カスタムタイトルをグローバルに設定できます。

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

`raw`

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

構文

::: raw
Wraps in a <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/] // defaults to /base\.css/
})
```

GitHub風味のアラート

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

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

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 { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      motd: 'VitePress is awesome',
      lorem: 'ipsum'
    }
  }
}
```

出力

export default { // Highlighted
  data () {
    return {
      msg: `Highlighted!
      This line isn't highlighted,
      but this and the next 2 are.`,
      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:<lines>]を使用してフォーカスする行数を定義できます。

入力

```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の後に=を追加することで、開始行番号をカスタマイズすることもできます。たとえば、:line-numbers=2は、コードブロックの行番号が2から始まることを意味します。

入力

```ts {1}
// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:line-numbers {1}
// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'
```

```ts:line-numbers=2 {1}
// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'
```

出力

// line-numbers is disabled by default
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// line-numbers is enabled
const line2 = 'This is line 2'
const line3 = 'This is line 3'

// line-numbers is enabled and start from 2
const line3 = 'This is line 3'
const line4 = 'This is line 4'

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

次の構文を使用して、既存のファイルからコードスニペットをインポートできます。

<<< @/filepath

行の強調表示もサポートしています。

<<< @/filepath{highlightLines}

入力

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

コードファイル

export default function () {
  // ..
}

出力

export default function () {
  // ..
}

TIP

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

<<< ../snippets/snippet.js

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

入力

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

コードファイル

// #region snippet
function foo() {
  // ..
}
// #endregion snippet

export default foo

出力

function foo() {
  // ..
}

次のように、中かっこ（{}）内に言語を指定することもできます。

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

<!-- with line highlighting: -->

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

<!-- with line numbers: -->

<<< @/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

<!-- filename is used as title by default -->

<<< @/snippets/snippet.js

<!-- you can provide a custom one too -->

<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region]

:::

出力

snippet.jsリージョン付きスニペット

export default function () {
  // ..
}

function foo() {
  // ..
}

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

ネストされていても、あるMarkdownファイルに別のMarkdownファイルをインクルードできます。

TIP

マークダウンのパスの先頭に @ を付けることもできます。これはソースルートとして機能します。デフォルトでは、srcDir が設定されていない限り、VitePress プロジェクトのルートになります。

例えば、次のように相対的なマークダウンファイルを含めることができます。

入力

# Docs

## Basics

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

パートファイル (parts/basics.md)

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

対応するコード

# Docs

## Basics

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

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

入力

# Docs

## Basics

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

パートファイル (parts/basics.md)

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

対応するコード

# Docs

## Basics

### Configuration

Can be created using `.foorc.json`.

選択された行範囲の形式は、{3,}, {,10}, {1,10} のように指定できます。

WARNING

ファイルが存在しない場合でもエラーは発生しないことに注意してください。したがって、この機能を使用する際には、コンテンツが期待どおりにレンダリングされていることを確認してください。

数式

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

npm add -D markdown-it-mathjax3

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

入力

When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are
$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$

**Maxwell's equations:**

| equation                                                                                                                                                                  | description                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| $\nabla \cdot \vec{\mathbf{B}}  = 0$                                                                                                                                      | divergence of $\vec{\mathbf{B}}$ is zero                                               |
| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t}  = \vec{\mathbf{0}}$                                                          | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\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 \neq 0$ の場合、次の方程式には2つの解があります。 $(a x^{2} + b x + c = 0)$ それらは

x = \frac{- b \pm \sqrt{b^{2} - 4 a c}}{2 a}

マクスウェルの方程式

方程式	説明
$\nabla \cdot \vec{B} = 0$	の発散 $\vec{B}$ はゼロです
$\nabla \times \vec{E} + \frac{1}{c} \frac{\partial \vec{B}}{\partial t} = \vec{0}$	の回転 $\vec{E}$ は変化率に比例します $\vec{B}$
$\nabla \times \vec{B} - \frac{1}{c} \frac{\partial \vec{E}}{\partial t} = \frac{4 π}{c} \vec{j} \nabla \cdot \vec{E} = 4 π ρ$	え？

画像の遅延読み込み

設定ファイルで lazyLoading を true に設定することにより、マークダウンを介して追加された各画像の遅延読み込みを有効にできます。

export default {
  markdown: {
    image: {
      // image lazy loading is disabled by default
      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: {
    // options for markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#usage
    anchor: {
      permalink: markdownItAnchor.permalink.headerLink()
    },

    // options for @mdit-vue/plugin-toc
    // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
    toc: { level: [1, 2] },

    config: (md) => {
      // use more markdown-it plugins!
      md.use(markdownItFoo)
    }
  }
})

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

Markdown拡張機能 ​

ヘッダーアンカー ​

カスタムアンカー ​

リンク ​

内部リンク ​

ページサフィックス ​

外部リンク ​

フロントマター ​

GitHubスタイルの表 ​

Emoji 🎉 ​

目次 ​

カスタムコンテナ ​

デフォルトタイトル ​

カスタムタイトル ​

raw ​

GitHub風味のアラート ​

コードブロックでの構文強調表示 ​

コードブロックでの行の強調表示 ​

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

コードブロックでの色付きの差分 ​

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

行番号 ​

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

コードグループ ​

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

数式 ​

画像の遅延読み込み ​

高度な設定 ​

Markdown拡張機能

ヘッダーアンカー

カスタムアンカー

リンク

内部リンク

ページサフィックス

外部リンク

フロントマター

GitHubスタイルの表

Emoji 🎉

目次

カスタムコンテナ

デフォルトタイトル

カスタムタイトル

`raw`

GitHub風味のアラート

コードブロックでの構文強調表示

コードブロックでの行の強調表示

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

コードブロックでの色付きの差分

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

行番号

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

コードグループ

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

数式

画像の遅延読み込み

高度な設定