vuepress + GitHub 搭建一个在线文档

vuepress在线文档效果 预览链接

这是一个简易的配置，更复杂的配置还需前往vuepress官网进行配置 ，功能很强

GitHub仓库地址

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://.github.io
# git push -f [email protected]:/.github.io.git master

# 如果发布到 https://.github.io/
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】，点击这里
  
• 看到这个界面就说明部署成功了， 访问链接就可以看到自己写的文档了