vuepress在线文档效果 预览链接
这是一个简易的配置，更复杂的配置还需前往vuepress官网进行配置 ，功能很强
1. 新建一个项目
- 新建一个文件夹 命名 my-docs （名字随意）
- my-docs/ 下新建一个 docs 文件夹
- 整体目录如下
说明： - dist : 打包后自动生成
- public : 放置一些静态文件（如：图片）
- config.js : 页面的一些配置 （如：头部导航、左侧导航等）
- chapter1 和 chapter1 是自己创建的（随意命名）— 他们是文章左侧的导航菜单
- README.md : 配置文件
- .gitignore: 忽略文件
- deploy.sh : 部署到【github】上的脚本文件
config.js 具体配置
// *注意: base的值为github仓库的名称
module.exports = {
base: '/my_docs/', /* github项目仓库名称 */
dest: 'docs/.vuepress/dist', /* 打包文件基础路径, 在命令所在目录下 */
title: 'TypeScript 入门', // 标题
description: '学习使用 TypeScript', // 标题下的描述
themeConfig: {
// 主题配置
sidebar: [ // 左侧导航
{
title: '初识 TypeScript', // 标题
collapsable: false, // 下级列表不可折叠
children: [ // 下级列表
'chapter1/day1',
'chapter1/day2',
'chapter1/day3'
]
},
{
title: 'TypeScript 常用语法',
collapsable: true,
children: [
'chapter2/day1',
'chapter2/day2',
'chapter2/day3',
]
},
]
}
}
README.md 文件具体配置
---
#首页
home: true
# 图标
heroImage: /vue3_logo.png
# 按钮文本
actionText: 开始学习 →
# 按钮点击跳转路径
actionLink: /chapter1/day1
---
deploy.sh 文件 具体配置 可以参照 vuepress官网
#!/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 [email protected]:<USERNAME>/<USERNAME>.github.io.git master
# 如果发布到 https://<USERNAME>.github.io/<REPO>
git push -f [email protected]:junfeng-git/my_docs.git master:gh-pages
cd -
注意： 【[email protected]:junfeng-git/my_docs.git】 这种形式push，
是需要在 github配置公钥的，否则在执行 npm run deploy 时 会报错 （具体怎么配置这里就不说了）
package.json 添加
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs",
"deploy": "bash deploy.sh"
},
注意： npm run deploy 这句命令最好是在 git Bash 命令行工具中执行 vscode中会报错
2. 部署到【github】上
- 在【github】上新建一个 仓库，仓库名称为【my_docs】(名称和 config.js文件中 base 的值对应 )
- 将项目和【github】上新建的仓库就行绑定，推送代码
- git Bash 命令行工具中 执行 npm run deploy ，新建的仓库中会多出一个 gh-pages 分支
- 点击 【gh-pages】分支，然后点击 【settings 】按钮
- 找到 【GitHub Pages】，点击这里
- 看到这个界面就说明部署成功了， 访问链接就可以看到自己写的文档了
