介绍
- VuePress 由两部分组成：第一部分是一个极简静态网站生成器 ，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题
- 注释：极简静态网站生成器 @vuepress/core
- 注释：插件 API 是由 Vue 驱动？
快速上手
yarn add -D vuepress # npm install -D vuepress
- 在 package.json 中添加一些 scripts
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
目录结构
.
├── docs
│ ├── .vuepress (可选的)用于存放全局的配置、组件、静态资源等
│ │ ├── components (可选的)该目录中的 Vue 组件将会被自动注册为全局组件。
│ │ ├── theme (可选的)用于存放本地主题。
│ │ │ └── Layout.vue
│ │ ├── public (可选的) 静态资源目录。注释：该文件夹内的文件会在编译时拷贝到静态文件目录中，但不代表静态文件一定要放这，有引用关系的静态文件被视为模块进行打包处理。
│ │ ├── styles (可选的)用于存放样式相关的文件。
│ │ │ ├── index.styl 将会被自动应用的全局样式文件，具有比默认样式更高的优先级。
│ │ │ └── palette.styl 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。
│ │ ├── templates (可选的, 谨慎配置) 存储 HTML 模板文件。
│ │ │ ├── dev.html 用于开发环境的 HTML 模板文件。
│ │ │ └── ssr.html 构建时基于 Vue SSR 的 HTML 模板文件。
│ │ ├── config.js (可选的) 配置文件的入口文件，也可以是 YML 或 toml。
│ │ └── enhanceApp.js (可选的) 客户端应用的增强。?
│ │
│ ├── README.md // /
│ ├── guide
│ │ └── README.md // /guide/
│ └── config.md // /config.html
│
└── package.json
基本配置
- 一个 VuePress 网站必要的配置文件是 .vuepress/config.js，它应该导出一个 JavaScript 对象：
module.exports = {
title: 'Hello VuePress',
description: 'Just playing around'
}
- VuePress 内置了基于 headers 的搜索 —— 它会自动为所有页面的标题、h2 和 h3 构建起一个简单的搜索索引。
- 可配置选项：https://vuepress.vuejs.org/zh/config/#基本配置
- 一个 VuePress 主题应该负责整个网站的布局和交互细节。
- 默认主题提供了一些选项，让你可以去自定义导航栏（navbar）、 侧边栏（sidebar）和 首页（homepage） 等
- 可以通过创建一个 .vuepress/enhanceApp.js 文件来做一些应用级别的配置
- enhanceApp.js 应该 export default 一个钩子函数，并接受一个包含了一些应用级别属性的对象作为参数。你可以使用这个钩子来安装一些附加的 Vue 插件、注册全局组件，或者增加额外的路由钩子等
// 使用异步函数也是可以的
export default ({
Vue, // VuePress 正在使用的 Vue 构造函数
options, // 附加到根实例的一些选项
router, // 当前应用的路由实例
siteData, // 站点元数据
isServer // 当前应用配置是处于 服务端渲染 或 客户端
}) => {
// ...做一些其他的应用级别的优化
}
TypeScript as Config
- VuePress supports type prompt and type checking for config file, as well as type prompt for default theme or custom theme.
- 注释：config.js支持ts类型提示
import { defineConfig } from "vuepress/config";
export default defineConfig({
// ...
});
- By default, defineConfig helper leverages the theme config type from default theme:
- If you use a custom theme, you can use the defineConfig4CustomTheme helper with ability to pass generic type for your theme:
- 注释：config.js中主题配置选项themeConfig默认提示默认主题支持的配置，可以通过defineConfig4CustomTheme自定义
import { defineConfig4CustomTheme } from "vuepress/config";
interface MyThemeConfig {
hello: string;
}
export default defineConfig4CustomTheme<MyThemeConfig>({
/**
* Type is `MyThemeConfig`
*/
themeConfig: {
hello: "vuepress"
}
});
import { defineConfig } from "vuepress/config";
export default defineConfig(ctx => ({
// do not execute babel compilation under development
evergreen: ctx.isProd
}));
静态资源
- 所有的 Markdown 文件都会被 webpack 编译成 Vue 组件，因此你可以，并且应该更倾向于使用相对路径（Relative URLs）来引用所有的静态资源
- 疑问：为什么要用相对路径？别名使用绝对路径应该更好呀
- 同样地，这在 *.vue 文件的模板中一样可以工作，图片将会被 url-loader 和 file-loader 处理，在运行生成静态文件的构建任务时，文件会被复制到正确的位置。
- 除此之外，你也使用 ~ 前缀来明确地指出这是一个 webpack 的模块请求，这将允许你通过 webpack 别名来引用文件或者 npm 的依赖：
// .vuepress/config.js
module.exports = {
configureWebpack: {
resolve: {
alias: {
'@alias': 'path/to/some/dir'
}
}
}
}
- 需要提供一个静态资源，但是它们并不直接被你的任何一个 markdown 文件或者主题组件引用 —— 举例来说，favicons 和 PWA 的图标，在这种情形下，你可以将它们放在 .vuepress/public 中， 它们最终会被复制到生成的静态文件夹中。
- 如果你的网站会被部署到一个非根路径，你将需要在 .vuepress/config.js 中设置 base，举例来说，如果你打算将你的网站部署到 https://foo.github.io/bar/，那么 base 的值就应该被设置为 "/bar/" (应当总是以斜杠开始，并以斜杠结束)。
- 有了基础路径（Base URL），如果你希望引用一张放在 .vuepress/public 中的图片，你需要使用这样路径：/bar/image.png，然而，一旦某一天你决定去修改 base，这样的路径引用将会显得异常脆弱。为了解决这个问题，VuePress 提供了内置的一个 helper $withBase（它被注入到了 Vue 的原型上），可以帮助你生成正确的路径：
- 不仅可以在你的 Vue 组件中使用上述的语法，在 Markdown 文件中亦是如此
- 一个 base 路径一旦被设置，它将会自动地作为前缀插入到 .vuepress/config.js 中所有以 / 开始的资源路径中。
<img :src="$withBase('/foo.png')" alt="foo">
Markdown 拓展
- 所有的标题将会自动地应用 anchor 链接，anchor 的渲染可以通过 markdown.anchor 来配置。
- 网站内部的链接，将会被转换成 <router-link> 用于 SPA 导航
- 每一个文件夹下的 README.md 或者 index.md 文件都会被自动编译为 index.html，对应的链接将被视为 /
[Home](/) <!-- 跳转到根部的 README.md -->
[foo](/foo/) <!-- 跳转到 foo 文件夹的 index.html -->
[foo heading](./#heading) <!-- 跳转到 foo/index.html 的特定标题位置 -->
[bar - three](../bar/three.md) <!-- 具体文件可以使用 .md 结尾（推荐） -->
[bar - four](../bar/four.html) <!-- 也可以用 .html -->
- VuePress 支持重定向到干净链接。如果一个链接 /foo 找不到，VuePress 会自行寻找一个可用的 /foo/ 或 /foo.html。反过来，当 /foo/ 或 /foo.html 中的一个找不到时，VuePress 也会尝试寻找另一个。借助这种特性，我们可以通过官方插件 vuepress-plugin-clean-urls 定制你的网站路径。
- 注释：服务器代理模式和哈希模式都是返回根html，然后由vue-router拦截url实现页面跳转，最终由前端路由代码兜底不存在的页面
- 注释：/foo 和 /foo/ 相同是 vue-router 的功能，/foo.html 应该是路由错误后向服务端发起页面请求
- vuepress-plugin-clean-urls 这个官方插件地址失效
- 无论是否使用了 permalink 和 clean-urls 插件，你的相对路径都应该依赖于当前的文件结构来定义。在上面的例子中，即使你将 /foo/one.md 的路径设为了 /foo/one/，你依然应该通过 ./two.md 来访问 /foo/two.md。
- 注释：插件只是改变路由对应方式，在编码时依然遵守相对路径。
- 生成页面和内部链接时，默认使用 .html 作为后缀。你可以通过 config.markdown.pageSuffix 进行自定义配置
- 外部的链接将会被自动地设置为 target="_blank" rel="noopener noreferrer"
- 注释：没有noopener的话，新的页面可以通过 window.opener 访问您的窗口对象，并且它可以使用 window.opener.location = newURL 将您的页面导航至不同的网址。新页面将与您的页面在同一个进程上运行，如果新页面正在执行开销极大的 JavaScript，您的页面性能可能会受影响
- 注释：使用noopener时，在决定是否打开新窗口/选项卡方面，除_top，_self和_parent 以外的非空目标名称都被视为_blank 。
- 注释：指示浏览器在导航到目标资源时省略Referer标头，否则会泄漏引用者信息，并且行为就像还指定了noopener关键字一样
- 注释：Referer 请求头包含了当前请求页面的来源页面的地址，即表示当前页面是通过此来源页面里的链接进入的。
- 可以自定义通过配置 config.markdown.externalLinks 来自定义外部链接的特性
- VuePress 提供了对 YAML front matter 开箱即用的支持
- 这些数据可以在当前 markdown 的正文，或者是任意的自定义或主题组件中使用。
---
title: Blogging Like a Hacker
lang: en-US
---
| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
:tada: :100:
- 目录
- 疑问：标题生成？
- 可以通过 markdown.toc 选项来配置
[[toc]]
- 自定义容器
- details 是折叠框
- vuepress-plugin-container用于注册自定义容器
::: tip
这是一个提示
:::
::: warning
这是一个警告
:::
::: danger
这是一个危险警告
:::
::: details
这是一个详情块，在 IE / Edge 中不生效
:::
::: danger STOP
危险区域，禁止通行
:::
::: details 点击查看代码
折叠起来的内容
:::
- VuePress 使用了 Prism 来为 markdown 中的代码块实现语法高亮。Prism 支持大量的编程语言，你需要做的只是在代码块的开始倒勾中附加一个有效的语言别名
export default {
name: 'MyComponent',
// ...
}
- 代码块中的行高亮
- 除了单行以外，你也可指定多行，行数区间，或是两者都指定
- 行数区间: 例如 {5-8}, {3-10}, {10-17}
- 多个单行: 例如 {4,7,9}
- 行数区间与多个单行: 例如 {4,7-13,16,23-27,40}
- 可以通过配置来为每个代码块显示行号
module.exports = {
markdown: {
lineNumbers: true
}
}
<<< @/filepath
// 也支持 行高亮
<<< @/../@vuepress/markdown/__tests__/fragments/snippet.js{2}
- 由于代码段的导入将在 webpack 编译之前执行，因此你无法使用 webpack 中的路径别名，此处的 @ 默认值是 process.cwd()
- 注释：process.cwd()方法返回 Node.js 进程的当前工作目录
- 疑问：代码段的导入为什么在编译之前执行？
- 为了只导入对应部分的代码，你也可运用 VS Code region。你可以在文件路径后方的 # 紧接着提供一个自定义的区域名称
<<< @/../@vuepress/markdown/__tests__/fragments/snippet-with-region.js#snippet{1}
- VuePress 使用 markdown-it 来渲染 Markdown，上述大多数的拓展也都是通过自定义的插件实现的。想要进一步的话，你可以通过 .vuepress/config.js 的 markdown 选项，来对当前的 markdown-it 实例做一些自定义的配置
在 Markdown 中使用 Vue