本文介绍从零开始使用VuePress搭建个人博客并且发布到GithubPages的过程。
快速上手
初始化项目
新建目录
mkdir vuepress-starter && cd vuepress-starter
生成package.json文件
yarn init -y
安装依赖
yarn add -D vuepress
创建第一篇文档
mkdir docs && echo '# Hello VuePress' > docs/README.md
运行项目
添加scripts
package.json
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
},
本地启动服务
yarn docs:dev
目录结构
推荐目录结构如下
.
├── docs
│ ├── .vuepress (可选的)
│ │ ├── components (可选的)
│ │ ├── theme (可选的)
│ │ │ └── Layout.vue
│ │ ├── public (可选的)
│ │ ├── styles (可选的)
│ │ │ ├── index.styl
│ │ │ └── palette.styl
│ │ ├── templates (可选的, 谨慎配置)
│ │ │ ├── dev.html
│ │ │ └── ssr.html
│ │ ├── config.js (可选的)
│ │ └── enhanceApp.js (可选的)
│ │
│ ├── README.md
│ ├── guide
│ │ └── README.md
│ └── config.md
│
└── package.json
详细的目录说明参看官方文档，这里列出主要修改的几个目和文件
docs/.vuepress: 存放全局的配置、组件、静态资源等。docs/.vuepress/public: 静态资源目录。docs/.vuepress/config.js: 配置文件的入口文件，也可以是YML或toml。docs/README.md: 站点首页，默认路由是/
基本配置
网站banner
docs/README.md
---
home: true
heroImage: /home.jpg
actionText: 开始了解 →
actionLink: /repository/
footer: CC0 Licensed | Copyright © 2020-alfalfaw
---
默认的静态资源目录为docs/.vuepress/public，/home.jpg表示的是docs/.vuepress/public目录下的home.jpg文件
网站标题和描述
docs/.vuepress/config.js
module.exports = {
title: '全栈日志',
description: '公众号：全栈日记'
}
静态路径
docs/.vuepress/config.js
通过配置别名来避免用绝对路径访问资源
module.exports = {
configureWebpack: {
resolve: {
alias: {
'@public': './public'
}
}
}
}
站点根目录
docs/.vuepress/config.js
module.exports = {
base: '/journals/'
}
比如，要将网站部署到 https://<USERNAME>.github.io/journals/，那么 base 的值就应该被设置为 "/journals/"
网站图标
docs/.vuepress/config.js
module.exports = {
head: [
[
'link',
{
rel: 'icon',
href: '/favicon.ico'
}
]
]
}
网站目录
const utils = require('./utils')
module.exports = {
themeConfig: {
editLinks: true,
docsDir: 'docs',
smoothScroll: true,
nav: [
{
text: '博客',
link: '/blog/'
},
{
text: '分享',
link: '/share/'
},
{
text: '面试',
link: '/interview/'
}
],
sidebar: utils.inferSiderbars(),
lastUpdated: '上次更新',
editLinkText: '在 GitHub 上编辑此页'
}
}
插件
@vuepress/plugin-active-header-links
页面滚动时自动激活侧边栏链接
yarn add -D @vuepress/plugin-active-header-links
使用
module.exports = {
plugins: ['@vuepress/active-header-links', {
sidebarLinkSelector: '.sidebar-link',
headerAnchorSelector: '.header-anchor'
}]
}
back-to-top
增加返回顶部按钮
yarn add -D @vuepress/plugin-back-to-top
使用
module.exports = {
plugins: ['@vuepress/back-to-top']
}
last-updated
显示更新时间
使用默认主题只需配置themeConfig.lastUpdated = '最后更新时间'
@vuepress/plugin-medium-zoom
安装
yarn add -D @vuepress/plugin-medium-zoom
使用
module.exports = {
plugins: ['@vuepress/medium-zoom']
}
yarn add -D @vuepress/plugin-search
搜索
安装
yarn add -D @vuepress/plugin-search
使用
// .vuepress/config.js or themePath/index.js
module.exports = {
plugins: [
['@vuepress/search', {
searchMaxSuggestions: 10
}]
]
}
@vuepress/plugin-google-analytics
网站统计
安装
yarn add -D @vuepress/plugin-google-analytics
使用
plugins: [
[
'@vuepress/google-analytics',
{
ga: 'G-XXX'
}
]
]
其中ga获取方式如下，
访问Google Analytics，点击左下角管理，然后创建媒体资源，点击刚才创建的媒体资源下的数据流，选择添加数据流，数据流类型选择网站
部署
以部署到Github Pages为例
deploy.sh
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run docs:build
# 进入生成的文件夹
cd docs/.vuepress/dist
# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master
# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:<USERNAME>/<REPO>.git main:gh-pages
cd -
赋予权限
sudo chmod u+x deploy.sh
每次部署时执行下面命令
./deploy.sh
