基于VuePress进行项目搭建
最近想搭建一个手册类的网站,就在网络中寻找手册模板,经过调研发现 VuePress 是一个受到诸多好评的前端框架,可以帮助我们快速搭建一个以内容为中心的静态网站。自己实际使用起来也觉得体验很舒适,开箱即用,上手很快。
VuePress是由 Vue 驱动的静态网站生成器,用户只需要关注文档内容的编写,非常适合编写技术文档以及个人博客。
下面记录一下个人站点 Life 的搭建步骤:
VuePress 的安装
安装Node.js,需要版本 >= 8.6,有以下 3 种安装方式
- 直接使用已编译好的包
- 源码安装
- Ubuntu 通过
apt-get
命令安装
# 直接使用已编译好的包
wget https://nodejs.org/dist/v18.13.0/node-v18.13.0-linux-x64.tar.xz
tar xf node-v18.13.0-linux-x64.tar.xz && rm node-v18.13.0-linux-x64.tar.xz
cd node-v18.13.0-linux-x64/
./bin/node -v
# 源码安装
wget https://nodejs.org/dist/v18.13.0/node-v18.13.0.tar.gz && tar zxf node-v18.13.0.tar.gz
cd node-*
sudo ./configure
sudo make
sudo make install
# 命令行安装
sudo apt-get install nodejs
sudo apt-get install npm
- 安装 yarn 包管理器
sudo npm install -g yarn
- 新建工程目录并初始化项目,安装本地依赖
mkdir project && cd project
yarn init # npm init
yarn add -D vuepress # npm install -D vuepress
- 创建第一篇文档
mkdir docs && echo '# Hello VuePress' > docs/README.md
- 在 package.json 中添加一些 scripts
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
- 启动服务器
yarn docs:dev
以上就搭建好了一个简单的 VuePress 文档,下面我们可以继续进行界面美化,个人觉得 VuePress 默认主题足够简约,同时也非常适合学习主题的相关配置。
下面给出一部分主题配置,建议结合官方说明文档一起学习。
基于默认主题的配置
注意当前目录为docs
。
使用示例页面,修改
README.md
如下--- home: true heroImage: /logo.jpg actionText: 快速上手 → actionLink: /zh/guide/ features: - title: 简洁至上 details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。 - title: Vue驱动 details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。 - title: 高性能 details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。 footer: MIT Licensed | Copyright © 2018-present Evan You ---
创建配置文件
mkdir .vuepress/ && cat /dev/null > .vuepress/config.js
module.exports = { title: 'VuePress', // 网站的标题 description: 'Hello VuePress', // 网站的描述,它将会以 <meta> 标签渲染到当前页面的 HTML 中 head: [ ['link', { rel: 'icon', href: '/favicon.ico' }] // 需要被注入到当前页面的 HTML <head> 中的标签 ], themeConfig: { logo: '/favicon.ico', // 配置导航栏logo(themeConfig.logo) nav: [ // 可指定链接跳转模式:默认target: '_blank'新窗口打开,_self当前窗口打开 { text: 'Home', link: '/' }, { text: '百度', link: 'https://www.baidu.com' }, { text: 'CSDN', link: 'https://blog.csdn.net', target: '_blank' }, { text: '豆瓣', link: 'https://movie.douban.com', target: '_self', rel: '' }, // 支持嵌套,形成下拉式的导航菜单 { text: '语言', ariaLabel: 'Language Menu', items: [ { text: '中文', link: '/language/chinese/' }, { text: '英文', link: '/language/english/' } ] } ], sidebar: 'auto' // 全局设置自动生成侧边栏 } }
下面就是可选步骤,主要包括使用主题以及网站发布。
安装社区主题
以vuepress-theme-reco
主题为例,该主题几乎继承 VuePress 默认主题的一切功能,因此该主题的配置也很简单。
主题安装
yarn add vuepress-theme-reco # npm install vuepress-theme-reco --save-dev
使用主题
修改.vuepress/config.js
配置文件module.exports = { theme: 'reco' }
部署项目
项目可以部署到个人服务器上,也可以使用 GitHub Pages 进行部署。我们通过命令行 npm run docs:build
生成静态文件,然后将生成好的静态文件上传到服务器上或者 Github 的 repo 上即可。
Q&A
Q1. npm运行报错Error: ENOSPC: System limit for number of file watchers reached
A: 文件监视程序的系统产生了限制,达到了默认的上限,需要增加限额,建议按需设置,一般而言设为 1 会占用 5k 的内存空间。
sudo sysctl fs.inotify.max_user_watches = 524288
# 永久修改,需要配置 /etc/sysctl.conf
echo fs.inotify.max_user_watches = 524288 | sudo tee -a /etc/sysctl.conf
Q2. Vue 报错error:0308010C:digital envelope routines::unsupported
A: node.js V17版本后使用了最近发布的OpenSSL3.0, 而OpenSSL3.0对允许算法和密钥大小增加了严格的限制。通过修改 package.json 中的 scripts
{
"scripts": {
"docs:dev": "export NODE_OPTIONS=--openssl-legacy-provider && vuepress dev docs",
"docs:build": "export NODE_OPTIONS=--openssl-legacy-provider && vuepress build docs"
}
}
如果你认为这篇文章还不错,可以考虑 为作者充电 ⚡️