VuePress
VuePress 基于 Vue 的静态网站生成器，风格简约，配置也比较简单
- 官网：https://vuepress.vuejs.org/zh/guide/getting-started.html
- 参考：https://juejin.cn/post/7041134607869149215
初始
1、安装
yarn add -D vuepress
2、创建你的第一篇文档，VuePress 会以 docs 为文档根目录，所以这个 README.md 相当于主页
mkdir docs && echo '# Hello VuePress' > docs/README.md
3、在 package.json 中添加一些 scripts
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
4、启动
yarn docs:dev
目录结构
VuePress 遵循 “约定优于配置” 的原则，推荐的目录结构如下：
.
├── 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/components: 该目录中的 Vue 组件将会被自动注册为全局组件。docs/.vuepress/theme: 用于存放本地主题。docs/.vuepress/styles: 用于存放样式相关的文件。docs/.vuepress/styles/index.styl: 将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级。docs/.vuepress/styles/palette.styl: 用于重写默认颜色常量，或者设置新的 stylus 颜色常量。docs/.vuepress/public: 静态资源目录。docs/.vuepress/templates: 存储 HTML 模板文件。docs/.vuepress/templates/dev.html: 用于开发环境的 HTML 模板文件。docs/.vuepress/templates/ssr.html: 构建时基于 Vue SSR 的 HTML 模板文件。docs/.vuepress/config.js: 配置文件的入口文件，也可以是YML或toml。docs/.vuepress/enhanceApp.js: 客户端应用的增强
基础配置
在文档目录下创建一个 .vuepress 目录，所有 VuePress 相关的文件都会被放在这里。此时你的项目结构可能是这样：
.
├─ docs
│ ├─ README.md
│ └─ .vuepress
│ └─ config.js
└─ package.json
在 .vuepress 文件夹下添加 config.js，配置网站的标题和描述，方便 SEO：
module.exports = {
title: 'TypeScript4 文档',
description: 'TypeScript4 最新官方文档翻译'
}
添加导航栏
- config.js的themeConfig.nav字段
我们现在在页首的右上角添加导航栏，修改 config.js:
module.exports = {
title: '...',
description: '...',
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{
text: '冴羽的 JavaScript 博客',
items: [
{ text: 'Github', link: 'https://github.com/mqyqingfeng' },
{ text: '掘金', link: 'https://juejin.cn/user/712139234359182/posts' }
]
}
]
}
}
添加侧边栏
- config.js的themeConfig.sidebar字段
现在我们添加一些 md 文档，目前文档的目录如下：
.
├─ docs
│ ├─ README.md
│ └─ .vuepress
│ └─ config.js
| └─ handbook
| └─ ConditionalTypes.md
| └─ Generics.md
└─ package.json
我们在 config.js 配置如下：
module.exports = {
themeConfig: {
nav: [...],
sidebar: [
{
title: '欢迎学习',
path: '/',
collapsable: false, // 不折叠
children: [
{ title: "学前必读", path: "/" }
]
},
{
title: "基础学习",
path: '/handbook/ConditionalTypes',
collapsable: false, // 不折叠
children: [
{ title: "条件类型", path: "/handbook/ConditionalTypes" },
{ title: "泛型", path: "/handbook/Generics" }
],
}
]
}
}
更换主题
现在基本的目录和导航功能已经实现，但如果我还想要加载 loading、切换动画、模式切换（暗黑模式）、返回顶部、评论等功能呢，为了简化开发成本，我们可以直接使用主题，这里使用的主题是 vuepress-theme-rec：
yarn add vuepress-theme-reco -D
然后在 config.js 里引用该主题：
module.exports = {
// ...
theme: 'reco'
// ...
}
刷新一下页面，我们会发现一些细节的改变，比如加载时的 loading 动画、以及支持切换暗黑模式：
设置语言
VuePress 默认的 lang 为 en-US，我们修改一下 config.js：
module.exports = {
// ...
locales: {
'/': {
lang: 'zh-CN'
}
},
// ...
}
开启目录结构
而 vuepress-theme-reco 将原有的侧边栏的中的多级标题移出，生成子侧边栏，放在了页面的右侧，如果你要全局开启，可在页面 config.js 里设置开启：
module.exports = {
//...
themeConfig: {
subSidebar: 'auto'
}
//...
}
修改主题颜色
你可以创建一个 .vuepress/styles/palette.styl 文件，文件代码如下：
$accentColor = #3178c6
自定义修改样式
如果你想自定义修改一些 DOM 元素的样式呢？就比如在暗黑模式下：
们发现用作强调的文字颜色比较暗淡，在暗黑模式下看不清楚，我想改下这个文字的颜色和背景色呢？
而 VuePress 提供了一种添加额外样式的简便方法。你可以创建一个 .vuepress/styles/index.styl 文件。这是一个 Stylus 文件，但你也可以使用正常的 CSS 语法。
我们在 .vupress 文件夹下创建这个目录，然后创建 index.styl 文件，代码如下：
// 通过检查，查看元素样式声明
.dark .content__default code {
background-color: rgba(58,58,92,0.7);
color: #fff;
}
部署
官方： https://vuepress.vuejs.org/zh/guide/deploy.html#heroku
- 在
docs/.vuepress/config.js中设置正确的base。如果你打算发布到
https://<USERNAME>.github.io/，则可以省略这一步，因为base默认即是"/"。如果你打算发布到
https://<USERNAME>.github.io/<REPO>/（也就是说你的仓库在https://github.com/<USERNAME>/<REPO>），则将base设置为"/<REPO>/"。
在你的项目中，创建一个如下的
deploy.sh文件你可以在你的持续集成的设置中，设置在每次 push 代码时自动运行上述脚本
部署到免费的 Github Pages 上。我们在 Github 上新建一个仓库,仓库名为vuePress-demo
对应，我们需要在 config.js 添加一个 base 路径配置：
module.exports = {
base: '/vuePress-demo/',
//...
}
然后我们在项目 目录下建立一个脚本文件：deploy.sh，注意修改一下对应的用户名和仓库名
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run docs:build
# 进入生成的文件夹
cd docs/.vuepress/dist
git init
git add -A
git commit -m 'deploy'
# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:qiuweikangdev/vuePress-demo.git master:dev
cd -
Github Actions
- 创建 Github access token (opens new window);
- 在你 github 仓库下，创建一个 secrets (opens new window)，填入刚创建的
token - 在项目根目录下的
.github/workflows目录（没有的话，请手动创建一个）下创建一个.yml或者.yaml文件，如:vuepress-deploy.yml;
创建一个工作流
- GitHub Actions 使用 YAML 语法定义工作流。每一个工作流保存为一个独立的 YAML 文件，目录是
.github/workflows。
- 在你的仓库，创建一个
.github/workflows/目录 - 在
.github/workflows/目录，创建一个文件，名为github-action.yml，添加下面的代码：
name: github-action
on: [push]
jobs:
check-bats-version:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-node@v2
with:
node-version: '14'
- run: npm install -g bats
- run: bats -v
3、提交这些改动，推送到github仓库
你的新 GitHub Actions 工作流文件就会被安装在你的仓库，当有人提交代码的时候，工作流就会自动执行。关于一个任务的执行历史，查看查看工作流活动章节。
name: 'github actions build and deploy gh-pages'
on:
push:
branches:
- master // 基于 master 分支，如果你的分支不是这个，请切换
jobs:
build-and-deploy:
runs-on: ubuntu-latest // 使用 ubuntu 服务器
steps:
- name: Checkout
uses: actions/checkout@v2.3.1
with:
persist-credentials: false
- name: install and build
run: | // 这里执行 安装 打包
npm install
npm run build
- name: Deploy
uses: JamesIves/github-pages-deploy-action@3.5.9 // 这里可引用别人的action部署插件
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }} // 这里需要设置成你的 token
BRANCH: gh-pages
FOLDER: docs/.vuepress/dist