一、创建项目
创建一个项目
// 创建文件夹 mkdir learnjtsdoc // 进入文件夹 cd learnjtsdoc // 初始化文件 npm init
初始化项目，并进行配置，如果你不想配置或者还不了解这些配置的意思，可以一直回车，后期可以在packages.json文件里修改
此时你的仓库就已经初始化好了,现在在编辑器里打开项目
二、安装vuepress
我是使用的2.x版本的vuepress，所以执行
npm install -D vuepress@next
安装完成后，此时我们可以看到左边目录结构多了几个文件
在package.json文件里添加这两个命令，第一个命令是启动本地预览，第二个是打包构建
"docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs"
在根目录下新建一个.gitignore文件，将不必要的文件忽略
node_modules //依赖包 .temp //运行时产生的缓存 .cache //运行时产生的缓存
此时就可以看到左边 4k+ 未提交的文件只剩几个
启动本地预览
npm run docs:dev
将本地地址粘贴到浏览器，就可以看到效果
但是只能看到404页面，说明你已经安装成功了，因为还没开始写文档，所以会默认显示404页面
下面开始配置
三、配置
在配置之前，先搭建好我们的目录结构
├─ docs │ ├─ .vuepress // 存放全局的配置、组件、静态资源等。 │ │ └─ public │ │ │ └─ images //存放图片 │ │ └─ config.ts // 配置文件的入口文件 │ ├─ pages // 存放页面 │ └─ README.md //文档的入口页面。 ├─ .gitignore └─ package.json
VuePress 站点的基本配置文件是 .vuepress/config.js ，但也同样支持 TypeScript 配置文件。为了显得洋气， 我也试试用 config.ts来配置
引入配置
开始进行最基本的配置
import { defineUserConfig, } from 'vuepress' export default defineUserConfig({ base:'/', lang: 'zh-CN', title: 'LearnJTs', description: 'JS工具类方法,手写常用js方法汇总', head: [['link', { rel: 'icon', href: '/images/logo.png' }]], })
我们可以看到配置中的一些字段，他们都有什么用呢？
- title 显示在左上角的网页名称以及首页在浏览器标签显示的title名称
- description 中的描述文字，用于SEO
- head里的内容 会注入到当前页面的
HTML <head>中的标签 - href 是浏览器的标签栏的网页图标，第一个'/'会遍历public文件夹的文件
这个时候你再运行
npm run docs:dev
就可以看到tab标签栏的内容，和导航条左上角的内容了
接下来才是重头戏，我们继续扩展
配置首页
我们的README.md就是我们的首页，接下来开始对他进行配置,这是我的网站首页的配置，你也可以先复制过去再修改
--- home: true heroImage: /images/logo.png heroText: JS工具库 tagline: 一点一滴都是进步 actions: - text: 快速上手 → link: /pages/introduce.md/ type: primary features: - title: 个人工具 details: JS工具类方法，手写常用js方法汇总，建造一个属于自己的工具库；不追求大而全，目标是小而实用 - title: 详细记录 details: 每一个函数都能正常调用。写这个库的目的是为了更好的学习JS，所以每行代码都有注释，并且有详细解释，好记性不如烂笔头。 - title: 技术极为先进 details: 使用目前极为先进的vue3和vuepress搭建，100%单元测试覆盖，目前函数方法使用js编写，后期将会使用TS改造 ---
我们可以看到这就是配置好后的效果
heroImage的地址配置第一个'/'默认指向的是docs/.vuepress/public，你需要在此文件夹放置你的首页图片。actionLink地址配置第一个'/'默认指向的是 docs/，若未路径文件不存在点击进去会跳转至404。
配置导航栏
导航栏还是在config.js中配置，新引入 defaultTheme
import { defineUserConfig, defaultTheme} from 'vuepress' export default defineUserConfig({ // ...之前的配置 //新增导航条的配置 theme: defaultTheme({ // tab栏的图标; 图片 / 会自动去public文件夹里找图片 logo: '/images/logo.png', // 顶部导航条 navbar: [ { text: '介绍', link: '/pages/introduce.md', }, // NavbarGroup { text: '教程', children: [ { text: '安装指南', link: '/pages/learnJTs/install_guide.md', // 该元素将一直处于激活状态 activeMatch: '/pages/learnJTs/install_guide.md', }, { text: 'API使用', link: '/pages/learnJTs/detail_usage.md', activeMatch: '/pages/learnJTs/detail_usage.md', }, { text: '待定...', link: '/pages/other/other.md', }, ], }, ], repo: 'https://github.com/dongyuanwai/learnjts', }), })
我们可以看到导航条就是这样的效果
接下来我用一张图，来让大家明白代码与生成效果的关系
相信大家看了这张图就明白了
导航条是建好了，但是页面还暂时无法跳转，因为此处点击菜单时跳转时，页面对应的markdown文件为空，会跳转至404页面。所以接下来我们开始建页面
vuepress的文件寻址:不同类型的文件都已经预设好不同的默认路径。比如说上一步的logo图片引用的路径，就是遍历
docs/.vuepress/public/images/logo.png寻找文件，我们只需要把图片放在这个文件夹就可以了。markdown的文件就按我写的放在docs/pages文件夹下，里面每个文件夹名字就是一个子路径。如此类推。每个不同类型的文件必须放置在按照规定好的位置。
侧边导航
import { defineUserConfig, defaultTheme} from 'vuepress' export default defineUserConfig({ // ...之前的配置 // 顶部导航条 navbar: [ // ...顶部导航条的配置 // 新增 侧边栏 sidebar: { // 不同子路径下的页面会使用不同的侧边栏 '/pages/learnJTs/': [ { text: '使用教程', children: ['install_guide.md', 'detail_usage.md'], }, ], '/pages/other/': [ { text: 'other', children: ['other.md'], }, ], }, }), })
添加md文档，添加好之后我的文档结构就是这样的了
为了方便演示，我把每一个md文件都把文件名写上
// # 文件名 # detail_usage.md
部署到github page
我们需要在learnjts目录下新建一个脚本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> # 修改为你的 github用户名/仓库名 git push -f git@github.com:dongyuanwai/learnjtsdoc.git master:gh-pages cd -
然后执行
sh deploy.sh
此时按照没有出现意外的剧情往下走 （如果出现了意外，请看最下面的意外二）
这句话的结果就是在你的仓库下面新建一个 gh-pages分支，然后把打包后的dist文件上传到这个分支上，此时你打开这个分支就可以看到它的目录结构，都是dist下面的文件
接下来就开始设置 settings了，根据下图的这五步，就能部署获取到一个链接
如果不出意外：打开这个链接，就能看到你的网站
如果出现意外：
意外一:没有样式
这可能是因为，配置文件里
config.ts里的base字段没有配置，或者配置错误
// 需要是github库名 base:'/learnjtsdoc/',
意外二:在执行 脚本命令
sh deploy.sh的时候就报错此时你可以按照脚本里的命令，在控制台一条一条的执行，查看是哪里出现了问题
我遇到了如上图的这样一个问题，原因是，dist目录下已经有.git文件了，所以无法初始化，运行 rm -rf .git删除.git,再继续运行命令
欢迎访问我的learnjts文档:LearnJTs文档
结尾
文档已经搭建好了，虽然只是有基础功能，但是也算是迈出了第一步
后续还会增加搜索，组件等功能......
