Markdown Extensions

VitePressには、Markdown Extensionsが組み込まれています。

ヘッダーアンカー

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

リンク

内部リンク、外部リンクともに特別な扱いを受けています。

内部リンク

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

例えば、次のようなディレクトリ構成があったとします。

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

And providing you are in foo/one.md:

[Home](/) <!-- ユーザーをルートの index.md に送ります。 -->
[foo](/foo/) <!-- foo ディレクトリの index.html にユーザーを送る。 -->
[foo heading](./#heading) <!-- foo インデックスファイル内の見出しにユーザーを固定します。 -->
[bar - three](../bar/three) <!-- 拡張子を省略することができます。 -->
[bar - three](../bar/three.md) <!-- .mdを追加することができます。 -->
[bar - four](../bar/four.html) <!-- または、.html を追加してください。 -->

ページサフィックス

ページと内部リンクは、デフォルトで .html という接尾辞で生成されます。

外部リンク

外部リンクは、自動的に target="_blank" rel="noreferrer" を取得します。

フロントマター

YAML frontmatterは、そのままサポートされます。

yaml

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

このデータは、すべてのカスタムコンポーネントとテーマコンポーネントとともに、ページの残りの部分から利用できるようになります。

詳しくは、Frontmatterをご覧ください。

GitHubスタイルのテーブル

Input

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

Output

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

Emoji 🎉

Input

:tada: :100:

Output

🎉 💯

全絵文字の一覧があります。

Input

[[toc]]

Output

TOCのレンダリングは markdown.toc オプションで設定することができます。

カスタムコンテナ

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

デフォルトのタイトル

Input

::: 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.
:::

Output

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.

カスタムタイトル

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

Input

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

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

Output

STOP

Danger zone, do not proceed

Click me to view the code

console.log('Hello, VitePress!')

`raw`

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

Syntax

::: raw
Wraps in a <div class="vp-raw">
:::

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

Details

Install required deps with your preferred package manager:
sh
```
$ yarn add -D postcss postcss-prefix-selector
```

Create a file named docs/.postcssrc.cjs and add this to it:

module.exports = {
  plugins: {
    'postcss-prefix-selector': {
      prefix: ':not(:where(.vp-raw *))',
      includeFiles: [/vp-doc\.css/],
      transform(prefix, _selector) {
        const [selector, pseudo = ''] = _selector.split(/(:\S*)$/)
        return selector + prefix + pseudo
      }
    }
  }
}

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

VitePressはShikiを使用して、Markdownコードブロック内の言語シンタックスをカラーテキストでハイライトしています。Shikiは様々なプログラミング言語をサポートしています。必要なことは、コードブロックの最初のバックティックに有効な言語エイリアスを追加することだけです。

Input

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

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

Output

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

html

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

有効言語一覧は、Shikiのリポジトリで公開されています。

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

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

Input

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

Output

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

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

行の範囲：例えば {5-8}, {3-10}, {10-17}
Multiple single lines: for example {4,7,9}
Line ranges and single lines: for example {4,7-13,16,23-27,40}

Input

```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'
    }
  }
}
```

Output

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 hl] というコメントを使うことで、その行に直接ハイライトを入れることも可能です。

Input

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

Output

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

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

行に // [!code focus] というコメントを付けると、その行にフォーカスが当たり、他の部分がぼやけます。

さらに、// [!code focus:<lines>] を使って、フォーカスする行数を定義することができます。

Input

なお、!codeの後に必要なスペースは1つだけですが、ここでは処理落ちを防ぐために2つにしています。

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

Output

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

コードブロックのカラー差分

行に // [!code --] または // [!code ++] コメントを追加すると、コードブロックの色を維持したまま、その行の diff を作成することができます。

Input

なお、!codeの後に必要なスペースは1つだけですが、ここでは処理落ちを防ぐために2つにしています。

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

Output

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

Errors and Warnings in Code Blocks

行に // [!コード警告] または // [!コードエラー] のコメントを追加すると、それに応じて色がつきます。

Input

なお、!codeの後に必要なスペースは1つだけですが、ここでは処理落ちを防ぐために2つにしています。

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

Output

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

ライン番号

設定により、各コードブロックの行番号を有効にすることができます。

export default {
  markdown: {
    lineNumbers: true
  }
}

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

フェンスで囲まれたコードブロックに :line-numbers / :no-line-numbers マークを追加することで、設定で設定した値をオーバーライドすることができます。

Input

```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'
```

Output

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

Import Code Snippets

以下の構文で、既存のファイルからコードスニペットをインポートすることができます。

<<< @/filepath

また、ラインハイライトにも対応しています。

<<< @/filepath{highlightLines}

Input

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

Code file

export default function () {
  // ..
}

Output

export default function () {
  // ..
}

TIP

値は、ソースルートに対応します。デフォルトでは、srcDirが設定されていない限り、VitePressプロジェクトのルートになります。

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

Input

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

Code file

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

export default foo

Output

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}

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

コードグループ

このように、複数のコードブロックをグループ化することができます。

Input

::: 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
```

:::

Output

config.jsconfig.ts

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

export default config

import type { UserConfig } from 'vitepress'

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

export default config

Markdownファイルのインクルージョン

マークダウン・ファイルを別のマークダウン・ファイルにインクルードすることができます。

Input

# Docs

## Basics

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

Part file (parts/basics.md)

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

Equivalent code

# Docs

## Basics

Some getting started stuff.

### Configuration

Can be created using `.foorc.json`.

WARNING

ただし、ファイルが存在しない場合はエラーを出しません。したがって、この機能を使用する場合は、コンテンツが期待通りにレンダリングされることを確認してください。

アドバンスト・コンフィグレーション

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

const anchor = require('markdown-it-anchor')

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    // https://github.com/valeriangalliat/markdown-it-anchor#usage
    anchor: {
      permalink: anchor.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(require('markdown-it-xxx'))
    }
  }
}

設定可能なプロパティの一覧はConfigsをご覧ください。アプリの設定(Config)

Markdown Extensions ​

ヘッダーアンカー ​

リンク ​

内部リンク ​

ページサフィックス ​

外部リンク ​

フロントマター ​

GitHubスタイルのテーブル ​

Emoji 🎉 ​

Table of Contents ​

カスタムコンテナ ​

デフォルトのタイトル ​

カスタムタイトル ​

raw ​

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

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

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

コードブロックのカラー差分 ​

Errors and Warnings in Code Blocks ​

ライン番号 ​

Import Code Snippets ​

コードグループ ​

Markdownファイルのインクルージョン ​

アドバンスト・コンフィグレーション ​

Markdown Extensions

ヘッダーアンカー

リンク

内部リンク

ページサフィックス

外部リンク

フロントマター

GitHubスタイルのテーブル

Emoji 🎉

Table of Contents

カスタムコンテナ

デフォルトのタイトル

カスタムタイトル

`raw`

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

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

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

コードブロックのカラー差分

Errors and Warnings in Code Blocks

ライン番号

Import Code Snippets

コードグループ

Markdownファイルのインクルージョン

アドバンスト・コンフィグレーション