使用VuePress搭建文档

时间 2019-11-06

标签使用 vuepress 搭建文档繁體版

原文原文链接

前言

公司交给我一个任务，搭建一个公司内部的前端文档，调研一番后，准备使用VuePress开发。固然，网上关于VuePress的好文章有很是多，原本不必再写一篇了；可是，写文章毕竟是对本身学习的一个总结，仍是写一篇吧！css

本文基于VuePress 1.xhtml

官方文档

VuePress前端

项目初始化

建立文件夹，生成.json文件vue

// 建立文件夹
mkdir docs

// 项目初始化 
npm init
复制代码

安装配置VuePress

// 进入
cd docs

// 项目安装VuePress
npm install -D vuepress

// 新建文件夹，'docs'不能改为别的名字，否则启动报错，
// error: 'no such file or directory, stat 'F:\web\docs\docs''
mkdir docs

// 新建一个 Markdown 文件
echo "# Hello VuePress!" > docs/README.md

// 启动预览
npx vuepress dev docs
复制代码

在浏览器输入http://localhost:8080/，能看到Hello VuePress!就表示启动成功了node

而后，配置package.jsongit

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
复制代码

配置后，从新启动github

npm run docs:dev
复制代码

刷新浏览器，还能够看到Hello VuePress!表示配置成功了web

测试生成静态HTMLnpm

npm run docs:build
复制代码

在docs文件夹下面多了.vuepress文件夹，.vuepress文件夹下面有个dist文件夹，里面结构以下json

|-assets
    └──css
    └──img
    └──js
|-404.html
|-index.html

复制代码

右键index.html在浏览器打开，你会发现样式有错误，这个的缘由是路径的问题，咱们设置一下，而后放到服务器上就行了

// 进入
cd .vuepress

// 建立配置文件
vim config.js

// 配置以下
module.exports = {
  // 设置网站标题
  title: '前端文档', 
  // 设置输出目录
  dest: './dist', 
  // 设置站点根路径，若是你在访问的地址是 'www.xxxx.com/wxDocs' 那么就设置成 '/wxDocs/'  
  base: '/wxDocs/' 
  // 添加 github 连接，可是这个要放在公司的内网服务器，因此为空
  // repo: '' 
}

// 打包
npm run docs:build
复制代码

你会发如今项目的根目录多了一个dist文件夹，把这个文件夹里面的全部东西上传到服务器，同时删除.vuepress文件夹下的dist文件夹

配置icon

// 进入
cd .vuepress

// 建立文件夹
mkdir public
复制代码

使用在线ps打开一张图片，更改图像大小为16*16 或者 32*32 或者64*64px，保存为ico格式，复制到public下面

更改config.js，添加以下代码

head: [['link', { rel: 'icon', href: '/logo.ico' }]]
复制代码

从新启动，刷新浏览器，看到浏览器导航栏出现图标，表示配置成功

配置首页

若是你想彻底自定义首页，那么就这样：

cd .vuepress

// 建立文件夹
mkdir components

// 建立首页文件，以正常写vue的方式在 'login.vue' 写代码
vim login.vue
复制代码

而后在README.md文件中修改成：

---
layout: login
---

<login />

复制代码

layout开启自定义设置，目标连接到你自定义的 login.vue 页面，而后下面的 <login /> 引入

若是不想自定义，那么使用默认的就能够了，这个是VuePress官方的默认配置首页

我这里考虑到到是内部文档，不开放给大众，上传到服务器，大众用户有可能会在搜索平台莫名搜索到文档地址，因此须要一个登陆页面，须要自定义一个登陆的首页，选择了layout使用vue彻底自定义

写好页面UI后，就能够写登陆跳转逻辑了，首先，在项目docs文件夹下新建文件夹：

// 在根目录新建home文件夹
mkdir home

// 进入
cd home 

// 新建 'README.md' 文件，必需要有，VuePress会自动把文件夹里的 'README.md' 转换为 'index.html' 文件，有这个才能跳转
vim README.md
复制代码

新建好后项目结构以下：

|-dist
|-docs
    └──.vuepress
    └──home
        └──README.md
    └──README.md
|-node_modules
|-package-lock.json
|-package.json
复制代码

而后给你登陆的按钮绑上一个click

methods: {
    goHome() {
      // 判断帐号密码是否正确的逻辑
      ...
      // 正确，跳转
      this.$router.push({ path: "/home/index.html" });
    }
  }
复制代码

这样你的首页就配置好了

配置导航

VuePress配置导航很是简单，只须要在config.js添加以下代码：

module.exports = {
  themeConfig: {
    nav: [
      {
        text: '首页',
        link: '/home/'
      },
      {
        text: 'H5',
        link: '/H5/'
      },
      {
        text: '规范',
        link: '/Standard/'
      }
      ...
    ]
  }
}

复制代码

而后在项目docs文件夹下新建和link一一对应的文件夹，文件夹下新建README.md就能够了

建好后，重启，刷新浏览器查看效果

tips：新建的文件夹和上面创建的home文件夹平级

配置侧边栏

配置侧边栏也很是的简单，首先配置config.js

module.exports = {
  themeConfig: {
    sidebar: {
      '/H5/': [
        'H5和app对接文档',
        '管理后台开发文档'
      ],
      '/Standard/': [
        'H5开发规范',
        'H5版本管理规范'
      ]
    }
  }
}
复制代码

而后，在对应的文件夹下新建.md文件就能够了，如：

|-h5
    └──H5和app对接文档.md
    └──管理后台开发文档.md
    └──README.md
|-Standard
    └──H5开发规范.md
    └──H5版本管理规范.md
    └──README.md

复制代码

tips: 你在config.js里配置的名字，要和你在文件夹下新建的名字一致，可是实际侧边栏的名字，是你在H5和app对接文档.md文件下写的第一个标题的名字

从新启动，刷新浏览器，你会看到设置已经生效的，可是貌似仍是有点问题，你在.md文件下生成的每个标题都会生成一个二级的页面，设置config.js取消掉

module.exports = {
  themeConfig: {
    sidebarDepth: '0',
  }
}
复制代码

个性化定制

在config.js里添加

module.exports = {
  // 代码块显示行号
  markdown: {
    lineNumbers: true
  },
}
复制代码

文档的滚动条太丑了，改一个样子

// 进入
cd .vuepress

// 新建'styles'文件夹
mkdir styles

// 新建 'index.styl' 和 'palete.styl'，VuePress使用 'stylus' 预处理器
vim index.styl
vim palete.styl
复制代码

index.styl 为全局自定义的样式，权限在默认之上
palete.styl 覆盖默认的主题配置

index.styl 样式

/*定义滚动条高宽及背景 高宽分别对应横竖滚动条的尺寸*/
::-webkit-scrollbar
{
  width: 8px;
  height: 8px;
  border-radius: 10px;
  background-color: #F5F5F5;
}

/*定义滚动条轨道 内阴影+圆角*/
::-webkit-scrollbar-track
{
  border-radius: 10px;
  -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.3);
  background-color: #F5F5F5;
}

/*定义滑块 内阴影+圆角*/
::-webkit-scrollbar-thumb
{
  border-radius: 10px;
  -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,.3);
  border-radius: 10px;
  /* 线性渐变 */
  background-image: -webkit-gradient(linear, 
  left bottom, left top,
   color-stop(0.44, rgb(60,186,146)), 
   color-stop(0.72, rgb(253,187,45)), 
   color-stop(0.86, rgb(253,187,45)));
  transition: 0.3s ease-in-out;
}
/*定义滑块悬浮样式*/
::-webkit-scrollbar-thumb:hover{
  background-image: -webkit-gradient(linear, 
  left bottom, left top, 
  color-stop(0.44, rgb(253,187,45)), 
  olor-stop(0.72, rgb(253,187,45)), 
  color-stop(0.86, rgb(60,186,146)));
  transition: 0.3s ease-in-out;
}

.site-name{
  background-image: -webkit-linear-gradient(left,
   #22c1c3, #fdbb2d 25%, #22c1c3 50%, #fdbb2d 75%, #22c1c3);
  -webkit-text-fill-color: transparent;
  -webkit-background-clip: text;
  -webkit-background-size: 200% 100%;
  -webkit-animation: myGradientChange 4s infinite linear;
  animation: myGradientChange 4s infinite linear;
}
@keyframes myGradientChange  {
  0%{ background-position: 0 0;}
  100% { background-position: -100% 0;}
}
复制代码

palete.styl 样式

// 点击状态
$accentColor = #3eaf7c

// 文字
$textColor = #2c3e50

// 边框
$borderColor = #eaecef

// 代码背景
$codeBgColor = #282c34
复制代码

若是你想要单独为某个页面写一个样式，能够这样

// 如今某一个页面的 '.md' 文件上添加
---
pageClass: custom-page-class
---
复制代码

而后在 index.styl 中添加

.theme-container.custom-page-class {
  /* page-specific rules */
}
复制代码

最后

VuePress总体上来讲仍是比较简单的，想写出新意来真的很是困难！

so，只能这样了。

参考

vuepress爬坑之旅
 VuePress 快速踩坑
 VuePress博客搭建笔记（二）个性化配置