几天前为了深入学习JS我手写了一个JS工具库，并且发布到了npm上
我把具体步骤，从零搭建再到发布上线的全部细节都写在这这一片文章上了：手写了一个JS工具库并发布到npm
既然已经写了JS工具库，那必须要有文档呀，要不然谁知道怎么使用！！！
所以今天这篇文章就介绍一下怎么使用vuepress2.x搭建一个文档，内容不深，小白也能看懂，因为我只是小小的写了一下 ^_^嘿嘿
文档效果可以点击此处查看☞:LearnJTs文档
一、创建项目
创建一个项目
// 创建文件夹
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文档
结尾
文档已经搭建好了，虽然只是有基础功能，但是也算是迈出了第一步
后续还会增加搜索，组件等功能......
我正在参与掘金技术社区创作者签约计划招募活动，点击链接报名投稿。
