Vitepress Basic

Table of Contents 目录

[[toc]]

Code Block 代码块

• Line Numbers 左侧展示行号

  可全局开启:

  // .vtepress/config.ts
  export default defineConfig({
    markdown: {
      // 所有 code block 均显示行号
      lineNumbers: true
    }
  });

  局部开启:

  ```js :line-numbers
  console.log('Hello world!');
  ```

  console.log('Hello world!');

  起始编号 0 (默认为 1):

  ```js :line-numbers=0
  console.log('Hello world!');
  ```

  console.log('Hello world!');

• 高亮指定行

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

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

• diff

  在代码同一行使用单行注释 // [!code --] 或 // [!code ++] 表示代码的增减

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

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

• 引入文件作为代码块

  <<< @/filepath

TIP

Vitepress 会自动由文件扩展名设置相应高亮语言, 如不合适或有自定义需求:

<<< @/filepath{js}

• Code Groups

  ::: code-group
  
  ```bash [pnpm]
  pnpm add @unocss/reset
  ```
  
  ```bash [yarn]
  yarn add @unocss/reset
  ```
  
  ```bash [npm]
  npm install @unocss/reset
  ```
  
  :::

  pnpm

  pnpm add @unocss/reset

  yarn

  yarn add @unocss/reset

  npm

  npm install @unocss/reset

• Focus 聚焦指定行

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

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

• twoslash

  得益于 @shikijs/vitepress-twoslash, 在代码块中加入 twoslash 即可实现类 IDE 的内联类型提示, 支持 ts 和 Vue 代码块:

  ```vue twoslash
  <script setup lang="ts">
  import {ref} from 'vue';
  
  const message = ref('Hello world!');
  </script>
  ```

  <script setup lang="ts">
  import {ref} from 'vue';
  
  const message = ref('Hello world!');
  </script>

Callout

• Custom Containers
• GitHub-flavored Alerts

支持以下类别:

• info
• tip
• warning
• danger
• details

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

::: details Click me to view the code

```js
console.log('Hello, VitePress!');
```

:::

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.

Click me to view the code

console.log('Hello, VitePress!');

Layout

• Layout

Layout 默认值为 doc, 可选值为:

• doc
• page
• home

可在 md 文件的 frontmatter 中配置, 如配置 layout: false 则不使用任何布局。

使用自定义布局:

---
layout: foo
---

Frontmatter

• title 标题, 会出现在 head title 标签中, 等同于 TDK 中的 T

  TIP

  TDK 为 Title、Description 和 Keywords 三个单词首字母合写, 为 SEO 常用术语

• description 描述, 等同于 TDK 中的 D

• keyword 关键词, 等同于 TDK 中的 K

• tag/tags 标签

• layout 布局, 默认值为 doc， 可选值

  • doc
  • page
  • home
  • custom 自定义布局

• sidebar 是否显示侧边栏 sidebar

在 vue 模板中使用:

<template>
  <div>{{ $frontmatter }}</div>
</template>

在 vue 脚本中使用:

<script setup lang="ts">
import {useData} from 'vitepress';

// frontmatter 为响应式数据 (Ref)
const {frontmatter} = useData();
</script>

在 md 中使用:

{{$frontmatter}}

注入 frontmatter:

// .vitepress/config.ts
export default defineConfig({
  // ...
  transformPageData(pageData) {
    // 须注入 frontmatter 的键值对
    const inject = {
      breadcrumb: true,
      pageInfo: true,
      heatmap: true,
      copyright: true
    };

    Object.keys(inject).forEach(key => {
      // 如 md frontmatter 中未配置该属性, 则使用默认值
      !(key in pageData.frontmatter) && (pageData.frontmatter[key] = inject[key as keyof typeof inject]);
    });
  }
});

withBase

• Runtime API withBase

<script setup lang="ts">
import {withBase} from 'vitepress';
</script>

<template>
  <!-- 指向根路由 -->
  <a :href="withBase('/')">Home</a>
</template>

*.data.js 或 *.data.ts

• Build-Time Data Loading

example.data.js:

import fs from 'fs';
import grayMatter from 'gray-matter';

export default {
  // ! 无法 watch md frontmatter 内容变动, 须重启方生效
  watch: ['docs/**/*.md'],
  load(files) {
    const json = files.map(file => {
      const content = fs.readFileSync(file, 'utf-8');

      const {data} = grayMatter(content);
      return data;
    });

    return json;
  }
};

使用:

<script setup lang="ts">
import {data as exampleData} from './example.data.js';
</script>

<template>
  <div>{{ exampleData }}</div>
</template>

TIP

Vitepress 在运行时会运行 *.data.js 中的 load 函数, 并使用命名导出了 data 变量

为避免变量名冲突, 建议引入时使用 as 别名:

import {data as exampleData} from './example.data.js';

Emoji

• markdown-it-emoji

常用的 emoji:

:white_check_mark:
:x:
:copyright:
:registered:
:construction:

✅
❌
©️
®️
🚧

脚注

这是一个脚注^[1]

数学公式

When $a\ne 0$, there are two solutions to $(a{x}^2+bx+c=0)$ and they are:

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

列表彩虹大纲线

• one
  • two
    • three
      • four
        • five
          • six
            • seven
              • eight
                • nine
                  • ten
                  • 10
                • 9
              • 8
            • 7
          • 6
        • 5
      • 4
    • 3
  • 2
• 1

• 1
  • 1.1
  • 1.2
    • 1.2.1
    • 1.2.2
      • 1.2.2.1
      • 1.2.2.2 -1.2.3
  • 1.3
• 2
  • 2.1
  • 2.2
    • 2.2.1
    • 2.2.2
• 3

Contributors

why

Changelog

Last edited 2 minutes ago

View full history

da5df4d-feat: update

---

1. 这是一个脚注 ↩︎