VitePress中文网

https://vitejs.cn/vitepress/

  • 注释：每一个 Markdown 文件将首先被编译成 HTML，接着作为一个 Vue 组件传入 Vite 处理通道
  • 注释：每个md都会被编译为静态的html文件，同时会被编译为js模块。当访问时首先获取的是对应url的html，后面页面跳转就都是加载js ，进行单页面跳转了。

什么是 VitePress？

  • 利用 Vue 3 改进的模板静态分析，它能尽可能的压缩静态内容。静态内容是以字符串的形式发送，而不是通过 JavaScript 渲染函数代码。因此 JS 负载更容易解析，hydration 也变得更快。（？）
  • VitePress 仍然允许用户在 Markdown 内容中自由的混合 Vue 组件
  • 不为每个请求发送元数据。这些 Page Weight 将从总页数中分离出来。每次请求只发送当前页面的元数据。客户端导航栏会一起获取新页面的组件和元数据。（？）
  • (WIP) i18n locale 数据也是按需获取（怎么实现？）
  • 鼓励使用没有经过转换的原生 JavaScript 以及主题化中使用 CSS 变量
  • VitePress 将有一个非常小的主题 API(更倾向于 JavaScript API 而不是文件布局约定)，而且很可能没有插件(所有定制都是在主题中完成)（？）

快速上手

  • 本地安装 VitePress
$ yarn add --dev vitepress
  • 在 package.json.添加一些script
{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }
}

配置

  • .vuepress 目录。所有 VuePress 相关的文件都将会被放在这里
  • 项目结构可能是这样
.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  └─ index.md
└─ package.json
  • 一个 VuePress 站点必要的配置文件是 .vuepress/config.js，它应当导出一个 JavaScript 对象：
module.exports = {
  title: 'Hello VitePress',
  description: 'Just playing around.'
}

静态资源处理

  • 所有的Markdown文件都通过Vite处理编译成Vue组件。你可以并且应当使用相对URL引用静态资源。
![An image](./image.png)
  • 可以在你的Markdown文件、主题中的*.vue组件、样式和纯.css文件使用绝对公共路径(基于项目根目录)或相对路径(基于你的文件系统)
    • 疑问：主题中的*.vue组件、样式和纯.css文件？
  • 常见的图片、媒体和字体文件类型会作为静态资源自动检测和包含
    • 注释：常见类型会被自动识别未静态资源进行处理
  • 所有被引用的静态资源，包括使用绝对路径的资源，在生产构建中会被复制到dist文件夹中，并重命名为hash文件名的文件。
  • 小于4kb的图片资源会转化为内联的base64字符。
  • 如果需要提供在你的Markdown或主题文件都没有直接引用的静态资源(如favicons和PWA 图标)。在项目根目录下的public目录可以用作转换舱口提供在源代码中没有引用的静态资源(如robots.txt)或必须保留完全相同文件名(没有hash)的文件。
    • 存放在public下的静态资源将原样复制到dist目录的根目录。
    • 应该使用根绝对路径引用放置在public文件夹中的文件。例如，文件public/icon.png在源代码中应该始终作为/icon.png被引用。
  • 如果你的站点部署在非根URL，你需要在 .vitepress/config.js中设置base选项
    • 如果你计划部署你的站点到https://foo.github.io/bar/，base选项就应该设置为'/bar/'(始终以/开始和结尾)。
  • 设置基础URL后，为了引用public中的图像，你就需要使用类似/bar/image.png的URL。 但是，当你觉得改变base值时，这样会很脆弱。 为此，VitePress提供了一个内置的助手$withBase(注入在Vue原型上)，用于生成正确的路径：
    • 还可以在Markdown文件中使用
foo

Markdown 扩展

  • 所有标题将自动添加anchor链接，Anchor的渲染可以使用markdown.anchor 选项来配置
  • 内部链接将会转化成路由链接用于SPA导航。
  • 同时，每一个文件夹下的 index.md 文件都会被自动编译为 index.html，对应的链接将被视为 /。
[Home](/) 
[foo](/foo/) 
[foo heading](./#heading) 
[bar - three](../bar/three) 
[bar - three](../bar/three.md) 
[bar - four](../bar/four.html)
  • 出站链接自动添加target="_blank" rel="noopener noreferrer"。
    • 注释：没有noopener的话，新的页面可以通过 window.opener 访问您的窗口对象，并且它可以使用 window.opener.location = newURL 将您的页面导航至不同的网址。新页面将与您的页面在同一个进程上运行，如果新页面正在执行开销极大的 JavaScript，您的页面性能可能会受影响
    • 注释：使用noopener时，在决定是否打开新窗口/选项卡方面，除_top，_self和_parent 以外的非空目标名称都被视为_blank 。
    • 注释：指示浏览器在导航到目标资源时省略Referer标头，否则会泄漏引用者信息，并且行为就像还指定了noopener关键字一样
    • 注释：Referer 请求头包含了当前请求页面的来源页面的地址，即表示当前页面是通过此来源页面里的链接进入的。
  • GitHub风格的表格
| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |
  • 表情符号:tada: https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.json
  • 目录[[toc]]
    • TOC的渲染可通过 markdown.toc 选项来配置。
    • 注释：必须配置后才会显示目录
  • 自定义容器(注释：等同于卡片，下例中STOP是标题，可选项)
::: danger STOP
Danger zone, do not proceed
:::
  • VitePress 通过 Prism来实现Markdown中语法块的语法高亮
    • 注释：Prism应该是编译时运行
  • 代码块中的行高亮js{4}(第4行高亮)
    • 行区间: 例如 {5-8}, {3-10}, {10-17}
    • 多个单行: 例如{4,7,9}
  • 通过配置为所有代码块启用行号：
module.exports = {
  markdown: {
    lineNumbers: true
  }
}
  • VitePress 使用 markdown-it 作为Markdown的渲染器。上述许多扩展是通过自定义插件实现。
    • 你可以通过 .vitepress/config.js中的markdown进一步定制markdown-it
module.exports = {
  markdown: {
    // options for markdown-it-anchor 锚点
    anchor: { permalink: false },

    // options for markdown-it-toc 目录
    toc: { includeLevel: [1, 2] },

    config: (md) => {
      // use more markdown-it plugins! 插件
      md.use(require('markdown-it-xxx'))
    }
  }
}

在 Markdown 中使用 Vue

  • 因为 VitePress 应用在生成静态构建时是通过 Node.js 服务端渲染的，因此所有 Vue 的使用必须符合编写通用代码的要求 https://ssr.vuejs.org/zh/guide/universal.html
    • 简而言之，要确保只在beforeMount 或 mounted时访问浏览器/DOM 的接口。
  • 如果你在使用或展示非 SSR 友好(比如包含自定义指令)的组件，你就可以使用ClientOnly将其包裹。
  • 并不能解决一些组件或库在导入时就试图访问浏览器 API 的问题。如果需要使用这样的组件或库，你需要在合适的生命周期钩子中动态导入：
  • 每一个 Markdown 文件将首先被编译成 HTML，接着作为一个 Vue 组件传入 Vite 处理通道，这意味着你可以在文本中使用 Vue 风格的插值
    • 可以在文本中使用 Vue 风格的插值
    • 也可以使用指令
    • 注释：md中可以直接使用html标签
{{ i }}
  • 编译后的组件可以访问 站点元数据和计算属性。
    • 注释：实际上是通过计算属性访问元数据
    • 注释：这些计算属性都是全局计算属性
  • 代码块(三个反引号包裹)将会被自动包裹在 v-pre 中
    • 注释：只是在反引号外围增加了自定义内容块
  • 如果你想要在内联 (inline) 的代码块或者普通文本中显示原始的大括号或一些 Vue 特定的语法，你需要使用自定义容器 v-pre来包裹
    • 注释：没有加会被作为vue风格的插值进行处理，即使在`包裹的代码块中
::: v-pre
`{{ This will be displayed as-is }}`
:::
  • 如果你的组件只是在少数几个地方使用，推荐你通过在你需要使用的文件中导入组件的方式来使用。
  • 在主题中注册全局组件，在.vitepress/theme/index.js中， 因为enhanceApp 函数接受 Vueapp对象，所以你可以像普通 Vue 插件那样注册组件
    • 注释：vue3 中全局注册组件是通过 createApp 创建的实例的component方法，所以下文中是名为app的变量
    • 确保自定义组件的名称包含连字符或是 PascalCase 格式。否者，它会被当成内联元素并包裹在

      标签内，这将会导致 HTML 渲染紊乱，

      标签中不允许放置任何块级元素。

  • 注释：以下为主题文件，主题文件是一个js文件，可以进行编程
import DefaultTheme from 'vitepress/theme'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    app.component('VueClickAwayExample', VueClickAwayExample)
  }
}
  • 注释：`包裹的代码，会被编译为code标签包裹的内容
  • 注释：<包裹的代码，除了在代码块中，都会被vue解析为组件
  • 输出的 HTML 由 markdown-it 完成。而解析后的标题由 VitePress 完成，用于侧边栏以及文档的标题。
    • 疑问：VitePress加载各文件，调用 markdown-it 转换为 html，然后作为 template 供vue使用？
  • VitePress 已经内建支持CSS 预处理器（支持.scss、 .sass、.less、 .styl 和 .stylus等文件）。这里不需要安装特定的 Vite 插件，只需要安装对应的预处理器自身。
# .scss and .sass
npm install -D sass
  • Markdown 文件中根节点使用