VuePress（未完）

• https://vuepress.vuejs.org/zh/guide/

介绍

• VuePress 由两部分组成：第一部分是一个极简静态网站生成器 ，它包含由 Vue 驱动的主题系统和插件 API，另一个部分是为书写技术文档而优化的默认主题
  • 注释：极简静态网站生成器 @vuepress/core
  • 注释：插件 API 是由 Vue 驱动？

快速上手

• 将 VuePress 安装为本地依赖

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

• 当你想要去自定义 templates/ssr.html 或 templates/dev.html 时，最好基于 默认的模板文件 来修改 https://github.com/vuejs/vuepress/blob/master/packages/%40vuepress/core/lib/client/index.dev.html
• 把 docs 目录作为 targetDir，packages.json 中所有的“文件的相对路径”都是相对于 docs 目录的

基本配置

• 一个 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"
  }
});

• You’ll be able to enjoy the type prompt of the official plugins:
• 注释：plugins插件配置项也支持类型提醒，且元组数组、字符串数组、对象三种方式都支持
• Type inference supports ISO Language Code for i18n
• 注释：多语言配置locales，国际语言编码 http://www.lingoes.net/en/translator/langcode.htm
• VuePress’s configuration can also be a function, while its first parameter is the current app context:
• 注释：defineConfig允许接受一个函数做为参数，该函数接收上下文对象作为参数 https://vuepress.vuejs.org/zh/plugin/context-api.html#context-api

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 的依赖：

![Image from alias](~@alias/image.png)
![Image from dependency](~some-dependency/image.png)

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

• GitHub 风格的表格
  • 注释：默认左对齐

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

• Emoji
  • 可以在这个列表找到所有可用的 Emoji https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.json

:tada: :100:

• 目录
  • 疑问：标题生成？
  • 可以通过 markdown.toc 选项来配置

[[toc]]

• 自定义容器
  • details 是折叠框
  • vuepress-plugin-container用于注册自定义容器

::: tip
这是一个提示
:::

::: warning
这是一个警告
:::

::: danger
这是一个危险警告
:::

::: details
这是一个详情块，在 IE / Edge 中不生效
:::

• 可以自定义块中的标题

::: danger STOP
危险区域，禁止通行
:::

::: details 点击查看代码
  折叠起来的内容
:::

• VuePress 使用了 Prism 来为 markdown 中的代码块实现语法高亮。Prism 支持大量的编程语言，你需要做的只是在代码块的开始倒勾中附加一个有效的语言别名
  • 注释：如下，博客园用法相同
  • 在 Prism 的网站上查看 合法的语言列表 https://prismjs.com/#languages-list

export default {
  name: 'MyComponent',
  // ...
}

• 代码块中的行高亮
  • 除了单行以外，你也可指定多行，行数区间，或是两者都指定
  • 行数区间: 例如 {5-8}, {3-10}, {10-17}
  • 多个单行: 例如 {4,7,9}
  • 行数区间与多个单行: 例如 {4,7-13,16,23-27,40}
• 可以通过配置来为每个代码块显示行号
  • 注释：显示1、2、3

module.exports = {
  markdown: {
    lineNumbers: true
  }
}

• 可以通过下述的语法导入已经存在的文件中的代码段

<<< @/filepath
// 也支持 行高亮
<<< @/../@vuepress/markdown/__tests__/fragments/snippet.js{2}

• 由于代码段的导入将在 webpack 编译之前执行，因此你无法使用 webpack 中的路径别名，此处的 @ 默认值是 process.cwd()
  • 注释：process.cwd()方法返回 Node.js 进程的当前工作目录
  • 疑问：代码段的导入为什么在编译之前执行？
• 为了只导入对应部分的代码，你也可运用 VS Code region。你可以在文件路径后方的 # 紧接着提供一个自定义的区域名称
  • 注释：VS Code region 是指 VSCode 的折叠块，VSCode允许标注折叠块合折叠块名称，不同语言标注方式不同 https://code.visualstudio.com/docs/editor/codebasics#_folding
  • 注释：在代码段导入时使用#+折叠块名称声明导入的代码块

<<< @/../@vuepress/markdown/__tests__/fragments/snippet-with-region.js#snippet{1}

• VuePress 使用 markdown-it 来渲染 Markdown，上述大多数的拓展也都是通过自定义的插件实现的。想要进一步的话，你可以通过 .vuepress/config.js 的 markdown 选项，来对当前的 markdown-it 实例做一些自定义的配置

在 Markdown 中使用 Vue