1、关于它
我们都知道vuepress是一个基于vue的文档系统,我们可以用来做静态资源站点,个人博客等。相比Docsify,hexo等,vuepress在SEO和二次开发等方面拥有绝对的优势,今天我们就一起来入门vuepress。
2、快速开始
2.1、前置依赖
vuepress的使用依赖NodeJs环境,所以首先我们需要安装NodeJs,安装指南点这里。
2.2、配置npm镜像源
npm config set registry https://registry.npm.taobao.org
2.3、安装vuepress
初始化前,记得将NodeJs的镜像源改为国内源,然后再初始化。
首先我们在当前路径下创建一个名为vuepress-demo\docs
的文件夹,再执行如下命令安装vuepress。
cd vuepress-demo
npm install -D vuepress
然后创建在docs下创建一个名为README.md的文件,并向其中输入以下内容:
# hello vuepress
2.4、配置script
然后我们在package.json中增加如下script:
{
"devDependencies": {
"vuepress": "^1.9.7"
},
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
接下来我们就可以开始启动开发服务器并在浏览器打开http://localhost:8080/
进行预览了。
2.5、demo预览
启动命令:npm run docs:dev
如上,恭喜你已经完成了第一个vuepress的demo。
3、配置vuepress
3.1、vuepress的目录结构
vuepress的目录结构非常简单,文旦开发者只需要专心维护docs
路径下的文档即可。
更多的关于样式和布局的配置点这里查看官方文档。
3.2、默认的页面路由
在docs
下,类似Docsify,默认的将README.md
作为一个路径的首页。
文件的相对路径 | 页面路由地址 |
---|---|
/README.md | / |
/guide/README.md | /guide/ |
/config.md | /config.html |
3.3、基本配置
初始的项目是没有任何配置的,所以上面我们看到的只是一个单页面,通过配置我们可以发掘出vuepress的更多功能。
我们在docs
路径下创建.vuepress/config.js
文件,在其中对vuepress项目进行配置。
3.3.1、配置站点标题和描述
在config.js中配置以下内容。
module.exports = {
title: 'Hello VuePress',
description: 'Just playing around'
}
重启服务器预览下:
3.3.2、配置默认首页
默认的首页只有一个空白页面和右上角的搜索框,我们可以通过修改README.md
实现首页的配置。
---
home: true
heroImage: https://excalidraw.com/apple-touch-icon.png
heroText: 这是标题
tagline: 这是副标题
actionText: 快速上手 →
actionLink: https://u1s1.vip
features:
- title: 简洁至上
details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。
- title: Vue驱动
details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。
- title: 高性能
details: 这是
footer: MIT Licensed | Copyright © 2018-present phyger
---
重新启动服务器,预览下:
如上,可以看到首页的效果已经出来了。
3.4、主题配置
3.4.1、导航栏logo配置
module.exports = {
title: 'Hello VuePress1',
description: 'Just playing around',
themeConfig: {
logo: 'https://excalidraw.com/apple-touch-icon.png',
}
}
效果:
3.4.2、导航栏链接
themeConfig: {
logo: 'https://excalidraw.com/apple-touch-icon.png',
nav: [
{ text: '首页', link: '/' },
{ text: '关于', link: 'https://u1s1.vip/about' },
{ text: '友链', link: 'https://u1s1.vip' },
]
}
效果:
打开新标签页和下拉菜单
themeConfig: {
logo: 'https://excalidraw.com/apple-touch-icon.png',
nav: [
{ text: '首页', link: '/' },
{ text: '关于', link: 'https://u1s1.vip/about' },
{ text: '友链', link: 'https://u1s1.vip' },
{
text: '下拉菜单',
ariaLabel: '这是提示语',
items: [
{ text: '下拉1', link: '/', target:'_self' },
{ text: '下拉2', link: 'https://u1s1.vip', target:'_blank' }
]
}
]
}
- target:'_blank' ,打开新的标签页
- target:'_self' ,在当前页打开
你还可以通过item嵌套实现下拉菜单的多级分组。
3.4.3、侧边栏
我们可以通过配置打开侧边栏。
themeConfig: {
sidebar: "auto",
sidebarDepth: 3
}
- 自动生成侧边栏。
- 设置侧边栏的标题深度为3。
效果:
除了自动生成侧边栏,我们还可以自定义侧边栏,类似Docsify。
themeConfig: {
sidebar: [
{
title: 'Group 1', // 必要的
path: '/page-a/', // 可选的, 标题的跳转链接,应为绝对路径且必须存在
collapsable: false, // 可选的, 默认值是 true,
sidebarDepth: 3, // 可选的, 默认值是 1
children: [
'/page-a/abc'
]
},
{
title: 'Group 2',
children: [ /* ... */ ],
initialOpenGroupIndex: -1 // 可选的, 默认值是 0
}
]
}
效果:
4、vuepress的热加载
你会发现,默认的script不能实现项目的热加载,在开发文档过程中很不方便。我们只需要为script增加一个--temp .temp
参数就可以实现热加载。
修改前:
{
"devDependencies": {
"vuepress": "^1.9.7"
},
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
修改后:
{
"devDependencies": {
"vuepress": "^1.9.7"
},
"scripts": {
"docs:dev": "vuepress dev docs --temp .temp",
"docs:build": "vuepress build docs"
}
}
评论区