VuePress 快速上手及基础配置

开始之前

1. 安装Node.js

   下载地址(版本需 >= 8.6)

2. 初始化项目

   yarn init

3. 安装VuePress

   yarn add -D vuepress

项目配置

目录结构

├─── docs
│   ├── README.md(首页)
│   ├── A(自定义文章目录)
│   ├── B(自定义文章目录)
│   ├── C(自定义文章目录)
│   └── .vuepress
│       ├── dist(生成静态文件的目录)
│       ├── styles(修改样式)
│       ├── public(存放静态资源)
│       └── config.js(配置文件)
└── package.json

首页

---
home: true
heroImage: /hero.webp
heroText: Example
tagline: Less is more.
actionText: Blog
actionLink: https://example.com
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + .webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer:  Copyright © 2017-2020 Example
---

你可以将相应的内容设置为 null 来禁用标题和副标题。

任何 YAML front matter 之后额外的内容将会以普通的 markdown 被渲染，并插入到 features 的后面。

config.js

module.exports = {
    title: 'Example', 
    description: null,
    base: '/notes/', // 项目部署位置，若为根目录删除本行
    head: [
        ['link', { rel: 'icon', href: 'https://example.com/favicon.ico' }]
      ],
    themeConfig: {
        // nav顶栏配置
        nav: [
            { text: 'page', link: '/page' },	// 单页面(文件名结尾)
            { text: 'folder', link: '/folder/' },	// 多页面(斜杠结尾，访问的是folder文件夹内的README.md)
            {	//分组
                text: 'Group Name',
                items: [	
                    { text: 'page', link: '/page' },	// item内配置同上
            		{ text: 'folder', link: '/folder/' }	// item内配置同上
                ]
            }
        ],
        sidebar: {
            // 侧边栏配置
            '/example/': [
                {	// 分组名
                    title: 'Group1',   // 必要的
                    collapsable: false, // 可选的, 默认值是 true,
                    sidebarDepth: 1,    // 可选的, 默认值是 1
                    //分组下文件['文件名','显示名称']
                    children: [
                      ['','目录'],	//文件名为空代表README.md
                      ['file1','文件1']	//当前路径可以省略./，md文件可以省略.md
                    ]
                  }
            ],
        sidebarDepth: 0, // 侧边栏深度 默认为1 最大为2
        search: false, // 关闭搜索
        smoothScroll: true, // 开启页面滚动
    },
    markdown: {
        lineNumbers: true // 开启代码行号
      }
}

package.json

在package.json中添加以下代码

"scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "deploy": "bash deploy.sh"
  },

Algolia 搜索

具体流程可参考 VuePress 博客优化之开启 Algolia 全文搜索

1. 进入申请页面，在表格内填写相应信息进行申请
2. 等待 Algolia 发送的确认邮件，回复 I am the maintainer of the website
3. 申请成功后，Algolia 会发送一封包含 AppId 等所需信息的右键
4. 进入爬虫后台，点击左侧 Edit 按钮，将其中的 pathsToMatch 后的域名修改为根域名，如 pathsToMatch: ["https://example.com/docs/**"] 修改为 pathsToMatch: ["https://example.com/**"]
5. 爬虫模板可以参考官方文档

从 v1.x 升级到 v2.x

安装

yarn add -D vuepress@next

默认主题设置

// config.ts
// v1.x
themeConfig: {
  // 配置项
},
    
// v2.x
const { defaultTheme } = require('@vuepress/theme-default');
theme: defaultTheme({
  // 配置项
}),

Navbar

• nav 配置项修改为 navbar

• 文章路径需添加 .md 后缀

Sidebar

• title 配置项修改为 text
• collapsable 配置项修改为 collapsible
• children 配置项从数组嵌套文章数组改为单一的文章数组
• 文章路径需添加 .md 后缀；侧边栏标题为文章的一级标题

// v1.x
children: [
  ['1.环境配置', '第1章 环境配置'],
  ['2.数据类型', '第2章 数据类型'],
  ['3.断言', '第3章 断言'],
  ['4.类', '第4章 类'],
  ['5.接口', '第5章 接口'],
  ['6.泛型', '第6章 泛型']
]

// v2.x
children: ['1.环境配置.md', '2.数据类型.md', '3.断言.md', '4.类.md', '5.接口.md', '6.泛型.md']

样式

• 预处理器从 Stylus 更换为 SASS
• palette.scss 用于覆盖默认主题的预定义 SASS 变量
• index.scss 用于添加额外的样式或覆盖默认样式

// index.scss
:root {
  scroll-behavior: smooth; // 平滑滚动
}

Algolia 搜索

// v1.x
algolia: {
  apiKey: 'xxx',
  indexName: 'xxx',
  appId: 'xxx'
},
    
// v2.x
npm i -D @vuepress/plugin-docsearch@next

plugins: [
  docsearchPlugin({
    apiKey: 'xxx',
    indexName: 'xxx',
    appId: 'xxx'
  }),
]