- 注释：每一个 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 而不是文件布局约定)，而且很可能没有插件(所有定制都是在主题中完成)（？）
快速上手
$ 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引用静态资源。
- 可以在你的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原型上)，用于生成正确的路径：
<img :src="$withBase('/foo.png')" alt="foo" />
Markdown 扩展
- 所有标题将自动添加anchor链接，Anchor的渲染可以使用markdown.anchor 选项来配置
- 内部链接将会转化成路由链接用于SPA导航。
- 同时，每一个文件夹下的 index.md 文件都会被自动编译为 index.html，对应的链接将被视为 /。
[Home](/) <!-- 跳转到根目录的index.md -->
[foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html-->
[foo heading](./#heading) <!-- 跳转到 foo/index.html 的特定标题位置 -->
[bar - three](../bar/three) <!-- 你可以忽略扩展名 -->
[bar - three](../bar/three.md) <!-- 具体文件可以使用 .md 结尾（推荐）-->
[bar - four](../bar/four.html) <!-- 也可以用 .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 |
::: danger STOP
Danger zone, do not proceed
:::
- VitePress 通过 Prism来实现Markdown中语法块的语法高亮
- 代码块中的行高亮
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
<ClientOnly>
<NonSSRFriendlyComponent/>
</ClientOnly>
- 并不能解决一些组件或库在导入时就试图访问浏览器 API 的问题。如果需要使用这样的组件或库，你需要在合适的生命周期钩子中动态导入：
<template>
<component v-if="dynamicComponent" :is="dynamicComponent"></component>
</template>
<script>
export default {
data() {
return {
dynamicComponent: null
}
},
mounted() {
import('./lib-that-access-window-on-import').then((module) => {
this.dynamicComponent = module.default
})
}
}
</script>
- 每一个 Markdown 文件将首先被编译成 HTML，接着作为一个 Vue 组件传入 Vite 处理通道，这意味着你可以在文本中使用 Vue 风格的插值
- 可以在文本中使用 Vue 风格的插值
- 也可以使用指令
- 注释：md中可以直接使用html标签
<span v-for="i in 3">{{ i }} </span>
- 编译后的组件可以访问 站点元数据和计算属性。
- 注释：实际上是通过计算属性访问元数据
- 注释：这些计算属性都是全局计算属性
- 代码块(三个反引号包裹)将会被自动包裹在 v-pre 中
- 如果你想要在内联 (inline) 的代码块或者普通文本中显示原始的大括号或一些 Vue 特定的语法，你需要使用自定义容器 v-pre来包裹
- 注释：没有加会被作为vue风格的插值进行处理，即使在`包裹的代码块中
::: v-pre
`{{ This will be displayed as-is }}`
:::
- 如果你的组件只是在少数几个地方使用，推荐你通过在你需要使用的文件中导入组件的方式来使用。
<CustomComponent />
<script setup>
import CustomComponent from '../components/CustomComponent.vue'
</script>
- 在主题中注册全局组件，在.vitepress/theme/index.js中， 因为enhanceApp 函数接受 Vueapp对象，所以你可以像普通 Vue 插件那样注册组件
- 注释：vue3 中全局注册组件是通过 createApp 创建的实例的component方法，所以下文中是名为app的变量
- 确保自定义组件的名称包含连字符或是 PascalCase 格式。否者，它会被当成内联元素并包裹在<p>标签内，这将会导致 HTML 渲染紊乱， <p> 标签中不允许放置任何块级元素。
- 注释：以下为主题文件，主题文件是一个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
<style lang="sass">
.title
font-size: 20px
</style>
- Markdown 文件中根节点使用<script> 或 <style>标签。这些内容会被从编译后的 HTML 抽离出来，用在 Vue 单页组件中<script> 或 <style>块中。
部署（注释：略）
Frontmatter
- 任何包含YAML frontmatter块的Markdown文件都将由gray-matter处理。
- 注释：gray-matter的作用
---
title: Hello
slug: home
---
<h1>Hello world!</h1>
// 转换为
{
content: '<h1>Hello world!</h1>',
data: {
title: 'Hello',
slug: 'home'
}
}
- Frontmatter块必须位于在Markdown文件的顶部，必须是有效的YAML格式，放置在三点划线之间。
---
title: Docs with VitePress
editLink: true
---
- 在三点划线之间，你可以设置预定义变量，甚至可以创建自定义变量。这些变量可以通过$frontmatter调用。
---
title: Docs with VitePress
editLink: true
---
# {{ $frontmatter.title }}
- 预定义变量
- title 当前页面的标题
- head 定义额外的需要注入的head标签。
- navbar 你可以通过在特定的页面上设置navbar:false来禁用导航。（注释：头部导航栏）
- sidebar 可以通过在特定页面上设置 sidebar: auto来显示侧边栏，或通过sidebar: false来禁用侧边栏。
- editLink 决定当前页面是否包含编辑链接。（疑问）
---
head:
- - meta
- name: description
content: hello
- - meta
- name: keywords
content: super duper SEO
---
- 在VitePress中，一些核心的 计算属性 可用在默认主题或自定义主题中。也可以直接用在使用Vue的Markdown页面中
- $site
{
base: '/',
lang: 'en-US', // （疑问）
title: 'VitePress', // 在YAML frontmatter和.vuepress/config.js中都可以配置（疑问）
description: 'Vite & Vue powered static site generator.', // 在.vuepress/config.js配置项（疑问）
head: [], // 应该是YAML frontmatter中的配置（疑问）
locales: {}, // 疑问
themeConfig: $themeConfig
}
{
locales: {}, // 疑问
repo: 'vuejs/vitepress', // 疑问
docsDir: 'docs', // 文档目录
editLinks: true, // 疑问
editLinkText: 'Edit this page on GitHub', // 疑问
lastUpdated: 'Last Updated', // 疑问
nav: [...], // 疑问，导航栏内容？
sidebar: { ... } // 疑问
}
{
relativePath: 'guide/global-computed.md', // 相对路径
title: 'Global Computed', // 应该是在YAML frontmatter的配置项
headers: [ // 疑问：锚点？
{ level: 2, title: '$site', slug: 'site' },
{ level: 2, title: '$page', slug: '$page' },
...
],
frontmatter: $frontmatter,
lastUpdated: 1606297645000
}
- $frontmatter
- $lang 当前页面的语言，默认：en-US
- $localePath 当前页面的本地路径，默认：/
- $title 当前页面的<title>标签值。
- $description 当前页面 <meta name= "description" content= "...">的content值
- $withBase 静态文件的基础路径
全局组件
- 可以在你的markdown文件或自定义主题配置中使用这些组件
- Content组件显示渲染后的Markdown内容。 当你创建自定义主题时有用
<template>
<h1>Custom Layout!</h1>
<Content />
</template>
- ClientOnly组件仅在客户端渲染其插槽
- OutboundLink 用于表示外部链接。在VitePress中，这个组件后面跟着外部链接。（疑问）
自定义
<!-- .vitepress/theme/Layout.vue -->
<template>
<h1>Custom Layout!</h1>
<Content /><!-- make sure to include markdown outlet -->
</template>
- 在 .vitepress/theme/index.js中引入
// .vitepress/theme/index.js
import Layout from './Layout.vue'
export default {
Layout,
NotFound: () => 'custom 404', // <- this is a Vue 3 functional component
enhanceApp({ app, router, siteData }) {
// app is the Vue 3 app instance from `createApp()`. router is VitePress'
// custom router. `siteData`` is a `ref`` of current site-level metadata.
}
}
与VuePress的区别（略）
应用级别配置
- 注释：在.vuepress/config.js中配置
- base 站点将部署在这个base URL。将站点部署到https://foo.github.io/bar/,那么你需要设置base为'/bar/'。注意，base需要以/开始并以/结尾。
- lang 站点的lang属性。这个属性将作为<html lang="en-US">标记渲染到页面HTML中。
- title 站点的标题。 这是所有页面标题的前缀，并显示在导航栏中。
- description 站点的描述。 这将作为<meta>标记渲染在页面HTML中。
module.exports = {
description: 'A VitePress site'
}
主题配置:Homepage（主页）
- VitePress 提供主页布局。想要使用，你需要在你的根目录index.md的YAML frontmatter中定义home: true并加上其他元数据。
---
home: true // 是否开启首页
heroImage: /logo.png // heroImage是一个网站设计术语，用于描述网站顶部的超大横幅图像
heroAlt: Logo image
heroText: Hero Title
tagline: Hero subtitle // 网页标语
actionText: Get Started // 首页跳转文本
actionLink: /guide/ // 首页跳转路由
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VitePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2019-present Evan You
---
主题配置:Algolia Search(注释：Algolia 搜索，一种搜索JSON数据的方法)
module.exports = {
themeConfig: {
algolia: {
apiKey: 'your_api_key',
indexName: 'index_name'
}
}
}
主题配置: Carbon Ads（注释：广告接入，略）