VuePress 快速踩坑

2018-04-27 admin

最近有个开源项目非常火,那就是尤小右开发的 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 属性的值总是以 / 开始并以 / 结束。

// 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 组件库。例如 ElementMint 等,通常我们在项目中使用这些 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。最后安利一波我正在做的开源项目 stylus-converter,有兴趣的同学可以一起参与,祝各位生活愉快,五一小长假玩的开心。

[转载]原文链接:https://zhuanlan.zhihu.com/p/36116211

本站文章除注明转载外,均为本站原创或编译。欢迎任何形式的转载,但请务必注明出处。

转载请注明:文章转载自 JavaScript中文网 [https://www.javascriptcn.com]

本文地址:https://www.javascriptcn.com/read-31206.html

文章标题:VuePress 快速踩坑

相关文章
vue中使用protobuf踩坑记
因公司需求需使用protobuf,然后就有了这个踩坑记录 什么是protobuf? 官方解释为: Protocol buffers are a flexible, efficient, automated mechanism for ...
2018-06-27
如何快速上手Vuex
在Mvc模式大行其道的今天,后端通过各种Mvc框架实现视图与数据模型的隔离,而前端这方面也发展迅速。vue实现了Dom与viewModel双向绑定,使其视图的更新影响模型,模型的更新影响视图,你会不会觉得这就是Mvc库呢,实则不然,因为他还...
2017-03-17
webpack import() 动态加载模块踩坑
webpack根据ES2015 loader 规范实现了用于动态加载的import()方法。 这个功能可以实现按需加载我们的代码,并且使用了promise式的回调,获取加载的包。 在代码中所有被import()的模块,都将打成一个单独的包,...
2018-07-16
Electron-TypeScript-React 快速开始脚手架
简介 快速启动一个Electron + TypeScritp + React的脚手架, 并且提供了React-Router/ React-Redux/ connected-react-router, 使用electron-builder打包...
2018-09-05
miti-ui之picker踩坑记
picker的数据来源为动态获取时,数据无法正常渲染!因为方法不对,所以坑大了!深刻地体会到’业不精,我之过’,谨以此文,深刻地记录一下踩坑及爬坑的整个过程,以便日后不再入坑,也给后来者提供一下参考 是mint-ui中的一个选择器组件,...
2018-05-16
Bootstrap页面缩小变形的快速解决办法
bootstrap布局是应用得很广泛的一种网页布局方法,例如:我们用一种中间内容很流行的布局分布:3-6-3式布局。代码如下 &lt;style type=&quot;text&#x2F;css&quot;&gt; body{width:1...
2017-02-13
webpack4 踩坑记
最近偶然想学习下webpack的配置,于是走上了webpack4踩坑的不归路。。。 webpack4默认的特性: 配置默认初始化一些配置, 比如 entry 默认 ‘./src’ 开发模式和发布模式, 插件默认内置 CommonsChu...
2018-05-02
vue-router 学习快速入门
vue-router 快速入门 配置路由 $ npm install vue-router --save routes.js import Home from &#x27;.&#x2F;pages&#x2F;Home.vue&#x27; ...
2017-03-14
JavaScript 性能优化之快速响应的用户界面
用于执行JavaScript和更新用户界面的进程通常被称为“浏览器UI线程”。JavaScript和用户界面更新在同一个进程中运行,因此一次只能处理一件事情。 ·任何JavaScript任务都不应当执行超过100毫秒,过长的运行时间导致UI...
2017-03-17
bootstrap折叠调用collapse()后data-parent不生效的快速解决办法
今天做的项目,用到了bootstrap的折叠功能,这个功能需要只展开一个折叠框,点击一个就会自动隐藏另一个,初始按照API做了一下,发现一切运行正常,但是测试的同事提了一个bug,说切换到其他模块后再切换回来,发现原先展开的折叠框没有折叠起...
2017-03-15
回到顶部