Markdown 擴充套件
VitePress 內建 Markdown 擴充套件。
標題錨點
標題會自動套用錨點連結。錨點的呈現方式可以使用 markdown.anchor 選項設定。
自訂錨點
若要為標題指定自訂錨點標籤，而不是使用自動產生的錨點，請在標題中加上後綴字元
# Using custom anchors {#my-anchor}這會讓你可以用 #my-anchor 連結到標題，而不是預設的 #using-custom-anchors。
連結
內部和外部連結都會有特別的處理方式。
內部連結
內部連結會轉換成路由連結，以進行 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](/) <!-- 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" 的外連連結
Frontmatter
YAML frontmatter 開箱即用
---
title: Blogging Like a Hacker
lang: en-US
---此資料將可供頁面其他部分使用，以及所有自訂和佈景主題元件。
更多詳細資訊，請參閱 Frontmatter。
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 |
表情符號 🎉
輸入
:tada: :100:輸出
🎉 💯
提供 所有表情符號的清單。
目錄
輸入
[[toc]]輸出
可以使用 markdown.toc 選項設定目錄的呈現方式。
自訂容器
可以依類型、標題和內容定義自訂容器。
預設標題
輸入
::: 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.
:::輸出
資訊
這是一個資訊方塊。
提示
這是一個提示。
警告
這是一個警告。
危險
這是一個危險警告。
詳細資訊
這是一個詳細資訊區塊。
自訂標題
您可以在容器的「類型」後方附加文字來設定自訂標題。
輸入
::: danger STOP
Danger zone, do not proceed
:::
::: details Click me to view the code
```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
Wraps in a <div class="vp-raw">
:::vp-raw 類別也可以直接用於元素。樣式隔離目前是選擇性加入
使用您偏好的套件管理員安裝
postcsssh$ npm add -D postcss建立一個名為
docs/postcss.config.mjs的檔案，並將此內容新增至其中jsimport { postcssIsolateStyles } from 'vitepress' export default { plugins: [postcssIsolateStyles()] }它在幕後使用
postcss-prefix-selector。您可以像這樣傳遞它的選項jspostcssIsolateStyles({ 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.注意
強調使用者應注意的資訊，即使是瀏覽時。
提示
協助使用者更成功的選用資訊。
重要
使用者成功所必需的關鍵資訊。
警告
由於潛在風險，要求使用者立即注意的重要內容。
小心
動作的負面潛在後果。
程式碼區塊中的語法突顯
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'
// ...
}<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 () {
// ..
}提示
@ 的值對應到來源根目錄。預設為 VitePress 專案根目錄，除非已設定 srcDir。或者，您也可以從相對路徑導入
<<< ../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
```
:::輸出
/**
* @type {import('vitepress').UserConfig}
*/
const config = {
// ...
}
export default configimport 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]
:::輸出
export default function () {
// ..
}function foo() {
// ..
}Markdown 檔案包含
您可以在另一個 Markdown 檔案中包含一個 Markdown 檔案，甚至可以巢狀包含。
提示
您也可以在 Markdown 路徑前加上 @，它會作為來源根目錄。預設為 VitePress 專案根目錄，除非已設定 srcDir。
例如，您可以使用以下方式包含一個相對的 Markdown 檔案
輸入
# 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}
警告
請注意，如果您的檔案不存在，這不會擲回錯誤。因此，在使用此功能時，請確保內容會如預期般呈現。
數學方程式
這目前是選擇加入。若要啟用它，您需要安裝 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?_ |輸出
When
麥克斯韋方程式
| 方程式 | 描述 |
|---|---|
| curl of | |
| 啥？ |
圖片延遲載入
你可以透過在設定檔中將 lazyLoading 設為 true 來啟用透過 markdown 加入的每張圖片的延遲載入
export default {
markdown: {
image: {
// image lazy loading is disabled by default
lazyLoading: true
}
}
}進階設定
VitePress 使用 markdown-it 作為 Markdown 渲染器。許多上述的擴充元件都是透過自訂外掛程式實作的。你可以進一步在 .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)
}
}
})請參閱 設定參考：應用程式設定 中可設定屬性的完整清單。