- 注釋：每一個 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（注釋：廣告接入，略）
