VuePress 快速踩坑小结


Posted in Javascript onFebruary 14, 2019

最近有个开源项目非常火,那就是尤小右开发的 VuePress,VuePress 可以让您非常方便的在 Markdown 文档中编写 Vue 代码,并且 VuePress 对编译后的 HTML 文件做了一些针对搜索引擎的优化。另外 VuePress 针对 Markdown 文件做了一些扩展使其功能更加强大,本文将围绕搭建一个 Github 的静态博客展开。

为项目加入 VuePress

第一步为您的项目安装 VuePress,如果您的项目代码中并没有 package.json文件,请先执行 npm init。

npm install -D vuepress // 或者 yarn add -D vuepress

// 在项目根目录下新加 docs 文件夹
mkdir docs

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

第二步在 package.json 中加入这些脚本,并运行。

// package.json
"scripts": {
 "docs:dev": "vuepress dev docs",
 "docs:build": "vuepress build docs"
}

// 本地运行文档
npm run docs:dev

// 编译打包生产静态 HTML 文件
npm run docs:build

VuePress 对 Markdown 做了一些扩展,使得我们可以在 Markdown 文件中使用 YAML 语法,VuePress 使用 ---来隔离 Markdown 语法。

---
// 该语法表示使用当前页面标题自动生成侧边栏
sidebar: auto
---

VuePress 基础配置

通过 VuePress 配置文件我们可以使用一些自定义的功能,譬如添加侧边栏,添加导航栏等。首先在 docs 目录下新建一个 .vuepress目录,并在该目录下方新建 config.js。

  1. VuePress 默认将文件打包在 .vuepress/dist目录下,我们可以通过 dest属性修改文件输出目录,例如将文件输出在项目根目录下的 dist文件夹中。
  2. 通过设置 repo属性,VuePress 会在导航栏中添加一个 Github 仓库的链接。
  3. 在 VuePress 中通过设置 title属性来设置网站的标题,它将会被用作所有页面标题的前缀,在默认主题下,它将应用在导航栏上。
  4. 在使用 VuePress 编写博客并发布到 Github pages 的时候,我们可能会遇到下图所显示的问题,页面已经有了,但是样式和 js 没有加载成功。我们可以通过配置 base 属性来解决这个问题, base 属性的默认值是 /。假如您准备将代码部署到 taoxusheng.github.io/mt-blog/ , 那么 base属性就应该被设置成 /mt-blog/。注意:base 属性的值总是以 / 开始并以 / 结束。

VuePress 快速踩坑小结

// dcos/.vuepress/config.js
module.exports = {
 title: 'my-blog', // 设置网站标题
 dest: './dist',  // 设置输出目录
 base: '/mt-blog/',// 设置站点根路径
 repo: 
 'https://github.com/TaoXuSheng/mt-blog' // 添加 github 链接
}

导航栏与侧边栏

在 VuePress 中如果想要为您的网站添加导航栏,可以通过设置 themeConfig.nav 来添加导航链接,通过设置 themeConfig.sidebar 属性来添加侧边栏。如果您的导航是一个下拉列表,可以通过 items 属性来设置。

// dcos/.vuepress/config.js
module.exports = {
 themeConfig: {
  // 添加导航栏
  nav: [
   { text: 'vue', link: '/' },
   { text: 'css', link: '/blog/' },
   { text: 'js', link: '/zhihu/' },
   {
    text: 'github',
    // 这里是下拉列表展现形式。
    items: [
     { text: 'focus-outside', link: 'https://github.com/TaoXuSheng/focus-outside' },
     { text: 'stylus-converter', link: 'https://github.com/TaoXuSheng/stylus-converter' },
    ]
   }
  ],
  // 为以下路由添加侧边栏
  sidebar: ['/', '/git', '/vue']
 }
}

有些时候我们可能需要一个多级侧边栏,例如一个博客系统,将一些类似的文章放在相同的目录下方,我们希望为这些目录的所有文件都添加侧边栏,就像下面这样的一个目录。

docs
 ├── README.md
 ├── vue
 │  ├─ README.md
 │  ├─ one.md
 │  └─ two.md
 └── css
   ├─ README.md
   ├─ three.md
   └─ four.md

对于多级目录的侧边栏,我们需要用使用对象描述的写法,下面的 /git/ 表示在 git 目录,默认指向 /git/README.md 文件。

// dcos/.vuepress/config.js
module.exports = {
 themeConfig: {
  sidebar: {
   '/vue/': [
    'one',
    'two'
   ],
   '/css/': [
    'three',
    'four'
   ]
  }
 }
}

在 VuePress 中注册组件

在 VuePress 中编写 Vue 代码,和我们通常的编写单文件的方式一致,有些时候我们有可能需要使用 Vue 的 UI 组件库。例如 Element,Mint 等,通常我们在项目中使用这些 UI 组件库的时候,我们都会在 main.js 或 botostrap.js 文件中统一注册。好在 VuePress 中也支持这种功能,我们可以通过创建一个 .vuepress/enhanceApp.js 文件来做一些应用级别的配置,这个文件 exprot default 一个钩子函数,在这个钩子中你可以做一些特殊处理,例如添加全局路由钩子,注册外部组件库。

// .vuepress/enhanceApp.js
// 全局注册 Element 组件库
import Vue from 'vue'
import Element from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

export default ({
 Vue,
 options,
 router
}) => {
 Vue.use(Element)
}

在 Vue 正常开发中,有些时候我们可能会需要做一些自定义的组件,在 VuePress 中我们可以在 .vuepress/components 目录中编写我们的自定义组件,VuePress 在编译时遍历该目录中所有的 *.vue 文件,并见它们注册为全局组件。

// 注册一个自定义组件
// docs/.vuepress/components/hello.vue
<template>
 <div class="cpt-hello">Hello VuePress Demo</div>
</template>

这样我们在 Markdown 文件编写 Vue 代码的时候就不需要注册注册这些组件,边可以直接在 Markdown 中使用了。

// docs/.vuepress/vue/README.md
<template>
 <div class="test-demo">
  {{ msg }}
  <my-hello></my-hello>
  <el-button>button</el-button>
 </div>
</template>

<script>
export default {
 data () {
  return {
   msg: 'Hello VuePress!'
  }
 }
}
</script>

部署到 Github pages

当我们将文档写好后就到了我们最关心的地方了,怎么将打包后的代码推送到远程仓库的 gh-pages 分支上,网上应该有很多文章描述怎么做,但是很多方法比较麻烦,还好有工具已经为我们解决了这个麻烦了。

// 1.下载 gh-pages 包
npm install -D gh-pages

// 2\. 在 package.json 文件上添加脚本命令
"scripts": {
 "docs:dev": "vuepress dev docs",
 "docs:build": "vuepress build docs",
 // 上面我修改了 VuePress 的输出目录,所以您如果没有修改 .vuepress/config.js
 // 的 dest 属性,应该将这里的 dist 改为 .vuepress/dist
 "deploy": "gh-pages -d dist",
 "deploy:build": "npm run docs:build && gh-pages -d dist"
}

// 3\. 打包并推送到 gh-pages 分支
npm run deploy:build

// 4.打开你的 Github pages, 地址是 https://<yourname>/github.io/<repo>

总结

相比较 Hexo 而言 VuePress 上手更加容易,功能也更强大,例如在 VuePress 可以注册自定义组件,而且 VuePress 中编写 Vue 和平时一样学习成本几乎为零。所以如果您正在开源一款 Vue 相关的库或是其他项目,您都可以使用 VuePress 作为您的文档编辑工具。虽然并没有完全将 VuePress 内容讲完,学完该篇文章相信你可以对 VuePress 有个大概的了解,您至少可以快速搭建一个博客,如果您想对 VuePress 有更多了解,请参考Vuepress 中文 API。

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持三水点靠木。

Javascript 相关文章推荐
js 获取元素下面所有li的两种方法
Apr 14 Javascript
javascript快速排序算法详解
Sep 17 Javascript
js的toUpperCase方法用法实例
Jan 27 Javascript
使用angularjs创建简单表格
Jan 21 Javascript
利用Vue.js实现checkbox的全选反选效果
Jan 18 Javascript
使用重写url机制实现验证码换一张功能
Aug 01 Javascript
layui实现点击按钮给table添加一行
Aug 10 Javascript
详解Vue CLI3配置解析之css.extract
Sep 14 Javascript
Vue Autocomplete 自动完成功能简单示例
May 25 Javascript
Vue+element+cookie记住密码功能的简单实现方法
Sep 20 Javascript
Javascript执行上下文顺序的深入讲解
Nov 04 Javascript
微信小程序APP的事件绑定以及传递参数时的冒泡和捕获
Apr 19 Javascript
使用vuepress搭建静态博客的示例代码
Feb 14 #Javascript
Node.js如何对SQLite的async/await封装详解
Feb 14 #Javascript
VuePress 静态网站生成方法步骤
Feb 14 #Javascript
extract-text-webpack-plugin用法详解
Feb 14 #Javascript
JavaScript&quot;模拟事件&quot;的注意要点详解
Feb 13 #Javascript
快速了解Node中的Stream流是什么
Feb 13 #Javascript
vue2.0+vue-router构建一个简单的列表页的示例代码
Feb 13 #Javascript
You might like
开发大型PHP项目的方法
2006/10/09 PHP
收藏的一个php小偷的核心程序
2007/04/09 PHP
PHP 多维数组排序实现代码
2009/08/05 PHP
PHP 手机归属地查询 api
2010/02/08 PHP
php simplexmlElement操作xml的命名空间实现代码
2011/01/04 PHP
php中inlcude()性能对比详解
2012/09/16 PHP
php操作xml入门之xml基本介绍及xml标签元素
2015/01/23 PHP
php+mysql+jquery实现日历签到功能
2017/02/27 PHP
php魔法函数与魔法常量使用介绍
2017/07/23 PHP
tp5框架使用composer实现日志记录功能示例
2019/01/10 PHP
JavaScript DOM 学习第二章 编辑文本
2010/02/19 Javascript
JQuery for与each性能比较分析
2013/05/14 Javascript
jQuery限制图片大小的方法
2016/05/25 Javascript
jQuery中each循环的跳出和结束实例
2017/08/16 jQuery
vue 中directive功能的简单实现
2018/01/05 Javascript
基于VuePress 轻量级静态网站生成器的实现方法
2018/04/17 Javascript
vue中子组件向父组件传递数据的实例代码(实现加减功能)
2018/04/20 Javascript
ES6 let和const定义变量与常量的应用实例分析
2019/06/27 Javascript
Vue.js数字输入框组件使用方法详解
2019/10/19 Javascript
Python读取sqlite数据库文件的方法分析
2017/08/07 Python
Python用for循环实现九九乘法表
2018/05/31 Python
python的scikit-learn将特征转成one-hot特征的方法
2018/07/10 Python
用Python分析3天破10亿的《我不是药神》到底神在哪?
2018/07/12 Python
python 数字类型和字符串类型的相互转换实例
2018/07/17 Python
Django项目中添加ldap登陆认证功能的实现
2019/04/04 Python
Python aiohttp百万并发极限测试实例分析
2019/10/26 Python
Python+Redis实现布隆过滤器
2019/12/08 Python
你不知道的5个HTML5新功能
2016/06/28 HTML / CSS
详解移动端HTML5页面端去掉input输入框的白色背景和边框(兼容Android和ios)
2016/12/15 HTML / CSS
英国时尚运动品牌的合集:The Sports Edit
2017/12/20 全球购物
PHP如何对用户密码进行加密
2014/07/31 面试题
产品开发计划书
2014/04/27 职场文书
节能环保口号
2014/06/12 职场文书
无刑事犯罪记录证明
2014/09/18 职场文书
2016年秋季开学典礼新闻稿
2015/11/25 职场文书
python DataFrame中stack()方法、unstack()方法和pivot()方法浅析
2022/04/06 Python