【VitePress】vitepress 中 markdown 写作使用

vitepress 中 markdown 使用

效果可以在我的博客查看 https://sonnenlicht77.github.io/docs.yy/guide/mdlearn/01.vpmd.html

markdown扩展
markdown语法

标题锚点

1. 标题会自动应用锚点。
   可以使用 markdown.anchor 选项配置锚点的渲染。

2. 自定义锚点

   要为标题指定自定义锚点而不是使用自动生成的锚点，请在标题后添加 {#my-anchor}。

   • 自定义锚点也可以在其他md文档中使用

   ## 自定义锚点标题 {#my-anchor}
   

这允许将标题链接为 #my-anchor，而不是默认的 #使用自定义锚点。

:::info

这是一个自定义锚点标题 {#my-anchor}

Lorem ipsum, or lipsum as it is sometimes known, is dummy text used in laying out print, graphic or web designs. The passage is attributed to an unknown typesetter in the 15th century who is thought to have scrambled parts of Cicero’s De Finibus Bonorum et Malorum for use in a type specimen book. It usually begins with:

“Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.”

The purpose of lorem ipsum is to create a natural looking block of text (sentence, paragraph, page, etc.) that doesn’t distract from the layout. A practice not without controversy, laying out pages with meaningless filler text can be very useful when the focus is meant to be on design, not content.

The passage experienced a surge in popularity during the 1960s when Letraset used it on their dry-transfer sheets, and again during the 90s as desktop publishers bundled the text with their software. Today it’s seen all around the web; on templates, websites, and stock designs. Use our generator to get your own, or read on for the authoritative history of lorem ipsum.

Lorem ipsum, or lipsum as it is sometimes known, is dummy text used in laying out print, graphic or web designs. The passage is attributed to an unknown typesetter in the 15th century who is thought to have scrambled parts of Cicero’s De Finibus Bonorum et Malorum for use in a type specimen book. It usually begins with:

“Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.”

The purpose of lorem ipsum is to create a natural looking block of text (sentence, paragraph, page, etc.) that doesn’t distract from the layout. A practice not without controversy, laying out pages with meaningless filler text can be very useful when the focus is meant to be on design, not content.

The passage experienced a surge in popularity during the 1960s when Letraset used it on their dry-transfer sheets, and again during the 90s as desktop publishers bundled the text with their software. Today it’s seen all around the web; on templates, websites, and stock designs. Use our generator to get your own, or read on for the authoritative history of lorem ipsum.

点击跳转至自定义锚点

:::

链接

内部和外部链接都会被特殊处理

1. 内部链接

   • 内部链接将转换为单页导航的路由链接。
   • 此外，子目录中包含的每个 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](/) 
   [foo](/foo/) 
   [foo heading](./#heading) 
   [bar - three](../bar/three) 
   [bar - three](../bar/three.md) 
   [bar - four](../bar/four.html) 
   

2. 页面后缀
   默认情况下，生成的页面和内部链接带有 .html 后缀。

3. 外部链接

   外部链接带有 target="blank" rel="noreferrer"

   • www.baidu.com

frontmatter

YAML格式的formatter开箱即用 具体frontmatter配置

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

输出 ⬇️ :

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

emoji

支持的所有emoji

:tada: :100:

输出 ⬇️ :

目录表

[[toc]]

输出 ⬇️ :
[[toc]]

自定义容器

自定义容器可以通过它们的类型、标题和内容来定义。

1. 默认标题

输入 ⬇️：

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

输出 ⬇️：
::: info
This is an info box.
:::

---

输入 ⬇️：

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

输出 ⬇️：
::: tip
This is a tip.
:::

---

输入 ⬇️：

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

输出 ⬇️：
::: warning
This is a warning.
:::

---

输入 ⬇️：

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

输出 ⬇️：
::: danger
This is a dangerous warning.
:::

---

输入 ⬇️：

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

输出 ⬇️：
::: details
This is a details block.
:::

---

2. 自定义标题

可以通过在容器的 “type” 之后附加文本设置自定义标题。

输入 ⬇️：

::: danger STOP
危险区域，请勿继续
:::

输出 ⬇️：
::: danger STOP
危险区域，请勿继续
:::

---

输入 ⬇️：

::: warning ⚠️
注意注意
:::

输出 ⬇️：
::: warning ⚠️
注意注意
:::

• 此外，可以通过在站点配置中添加以下内容来全局设置自定义标题，如果不是用英语书写，这会很有帮助：

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

3. raw

后面再来补充

Github风格的警报

语法

> [!NOTE]
> 强调用户在快速浏览文档时也不应忽略的重要信息。

效果

[!NOTE]
强调用户在快速浏览文档时也不应忽略的重要信息。

语法

> [!TIP]
> 有助于用户更顺利达成目标的建议性信息。

效果

[!TIP]
有助于用户更顺利达成目标的建议性信息。
语法

> [!IMPORTANT]
> 对用户达成目标至关重要的信息。

效果

[!IMPORTANT]
对用户达成目标至关重要的信息。
语法

> [!WARNING]
> 因为可能存在风险，所以需要用户立即关注的关键内容。

效果

[!WARNING]
因为可能存在风险，所以需要用户立即关注的关键内容。

语法

> [!CAUTION]
> 行为可能带来的负面影响。

效果

[!CAUTION]
行为可能带来的负面影响。

代码块

语法高亮

• VitePress 使用 Shiki 在 Markdown 代码块中使用彩色文本实现语法高亮。
• Shiki 支持多种编程语言。
• 需要做的就是将有效的语言别名附加到代码块的开头：
• 还可以全局配置中自定义语法高亮主题。
  • 配置markdown选项
  • 所有可配置的选项

// config.ts js高亮
import { defineConfig } from 'vitepress'
export default defineConfig({})

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

行高亮

可以通过在代码块的开头添加 {4} 来突出显示第 4 行。

```js{4} 

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

• 也可以使用 // [!code highlight] 注释实现行高亮。

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

聚焦

代码块中聚焦到某一行。

• 在某一行上添加 // [!code focus] 注释将聚焦它并模糊代码的其他部分。

• 此外，可以使用 // [!code focus:] 定义要聚焦的行数。

  • 可以使用 // [!code focus:-] 定义要聚焦的行范围。
  • 例如 : [!code focus:5]
    • 从当前行开始的连续5行代码

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

// [!code focus:3] 高亮从当前行开始的连续5行代码
export default {
  data () {
    return {
      msg: 'Focused!' 
    }
  }
}

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

颜色差异

在某一行添加 // [!code --] 或 // [!code ++] 注释将会为该行创建 diff，同时保留代码块的颜色。

// [!code --]  // 标记删除的行（红色背景）
// [!code ++]  // 标记新增的行（绿色背景）

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

高亮 “错误” 和 “警告”

• “错误”: //[!code warning]
• “警告” : //[!code error]

export default {
  data () {
    return {
      errMsg: 'Error', // [!code error] 错误
      warnMsg: 'Warning' // [!code warning] 警告
    }
  }
}

行号

• 全局通过以下配置为每个代码块启用行号

  // config.ts
  export default {
    markdown: {
      lineNumbers: true
    }
  }
  

• 在代码块中添加:

  • 可以在代码块中添加 :line-numbers / :no-line-numbers 标记来覆盖在配置中的设置。
  • 还可以通过在 :line-numbers 之后添加 = 来自定义起始行号，
    • 例如:line-numbers=2 表示 代码块中的行号从 2 开始。

  // 默认禁用行号
  const line2 = 'This is line 2'
  const line3 = 'This is line 3'
  
  

  // 启用行号
  const line2 = 'This is line 2'
  const line3 = 'This is line 3'
  

  // 行号已启用，并从 2 开始
  const line3 = 'This is line 3'
  const line4 = 'This is line 4'
  

导入代码片段

可以通过下面的语法来从现有文件中导入代码片段：

<<< @/filepath

同时支持行高亮:

<<< @/filepath{highlightLines}

输入 ⬇️ :

<<< @/utils/demo.js{3,8 js:line-numbers }

Code file

// ./docs/utils/demo.js
export default function demo() {
  // 1. 定义一个数组
  const arr = [1, 2, 3, 4, 5];

  return arr.reduce((acc, cur) => {
    return acc + cur;
  }, 0)
}

输出 ⬇️ :

<<< @/utils/demo.js{3,8 js:line-numbers}

• 也可以使用 VS Code region 来只包含代码文件的相应部分。
  • 可以在文件目录后面的 # 符号后提供一个自定义的区域名：

Code file

export default function demo() {
  // 1. 定义一个数组
  const arr = [1, 2, 3, 4, 5];
  // #region demo
  return arr.reduce((acc, cur) => {
    return acc + cur;
  }, 0)
  // #endregion demo
}

输入：

<<< @/utils/demo.js#demo{1 js:line-numbers}

输出 ⬇️ :

<<< @/utils/demo.js#demo{1 js:line-numbers}

代码组

可以对多个代码块进行分组：

• 可以通过在代码块中添加 ::: code-group , :::来创建一个代码组。

  • 在开始代码块中添加 [组名] 来为代码组项指定标题。

    • ts [config.ts]
    • js [config.js]

::: code-group

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

export default config

import type { UserConfig } from 'vitepress'

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

export default config

:::

• 导入代码块

::: code-group

<<< @/utils/demo.js{3,8 js:line-numbers}

<<< @/utils/demo.js#demo{1 js:line-numbers} [demoJS的region name]
:::

• 常见的使用场景：使用不同工具安装vitepress的命令行

::: code-group

npm add -D vitepress

pnpm add -D vitepress

yarn add -D vitepress

yarn add -D vitepress vue

bun add -D vitepress

:::

包含 markdown 文件

可以像这样在一个 markdown 文件中包含另一个 markdown 文件，甚至是内嵌的。

• 使用相对路径包含MD文件：

  # Docs
  
  ## Basics
  
  
  

basics.md

一个 markdown demo  

  #### 标题3

    
    const  obj = {
      name:'why'
    }

    function foo(){
      console.log('foo function');
    }
    

• 输入

  # Docs
  
  ## Basics
  
  
  
  

• 输出⬇️

  # Docs
  
  ## Basics
  
  一个 markdown demo  
  
   ### 标题3
  
  
     const  obj = {
       name:'why'
     }
  
     function foo(){
       console.log('foo function');
     }
  
  

数学方程

需要安装 markdown-it-mathjax3，在配置文件中设置markdown.math 为 true：

npm add -D markdown-it-mathjax3

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

图片懒加载

通过在配置文件中将 lazyLoading 设置为 true，可以为通过 markdown 添加的每张图片启用懒加载。

export default {
  markdown: {
    image: {
      // 默认禁用；设置为 true 可为所有图片启用懒加载。
      lazyLoading: true
    }
  }
}

高级配置

VitePress 使用 markdown-it 作为 Markdown 渲染器。上面提到的很多扩展功能都是通过自定义插件实现的。

• 使用 .vitepress/config.js 中的 markdown 选项来进一步自定义 markdown-it 实例。

markdown配置