VuePress

VuePress

这篇文章主要是记录自己在使用VuePress过程中所遇到的问题以及如何一步一步的解决问题。

安装vuepress前,请确保你的 Node.js 版本 >= 8

全局安装

# 安装
yarn global add vuepress 或者:npm install -g vuepress

<span class="hljs-comment"># 新建一个 markdown 文件
echo <span class="hljs-string">'# Hello VuePress!' > README.md

<span class="hljs-comment"># 开始写作
vuepress dev .

<span class="hljs-comment"># 构建静态文件
vuepress build .</span></span></span></span></span></span></span></code>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

注意 :`vuepress dev .`和`vuepress build .`后面的`.`。

## 在现有项目中安装

<pre><code class="hljs dockerfile"><span class="hljs-comment"># 将 vuepress 作为一个本地依赖安装
yarn <span class="hljs-keyword">add<span class="bash"> -D vuepress 或者:npm install -D vuepress

<span class="hljs-comment"># 新建一个 docs 文件夹
mkdir docs

<span class="hljs-comment"># 新建一个 markdown 文件
echo <span class="hljs-string">'# Hello VuePress!' > docs/README.md

<span class="hljs-comment"># 开始写作
npx vuepress dev docs</span></span></span></span></span></span></span></code>

接着,在 package.json 里加一些脚本:

<pre><code class="hljs json">{
  <span class="hljs-attr">"scripts": {
    <span class="hljs-attr">"docs:dev": <span class="hljs-string">"vuepress dev docs",
    <span class="hljs-attr">"docs:build": <span class="hljs-string">"vuepress build docs"
  }
}</span></span></span></span></span></code>
1
2
3
4

开始写作

<pre><code class="hljs less"><span class="hljs-selector-tag">yarn <span class="hljs-selector-tag">docs<span class="hljs-selector-pseudo">:dev 或者:<span class="hljs-selector-tag">npm <span class="hljs-selector-tag">run <span class="hljs-selector-tag">docs<span class="hljs-selector-pseudo">:dev</span></span></span></span></span></span></span></code>

第一个坑:我的项目就是依赖webpack 3.6.0同时也是用npm安装依赖,然后继续使用npm安装vuepress,然后执行npx vuepress dev docs的时候报错了,上网查了好久也没有解决问题,最后使用yarn安装vuepress成功了。

如果你的现有项目依赖了 webpack 3.x,推荐使用 yarn而不是 npm 来安装 vuepress。

要生成静态的 HTML 文件,运行:

<pre><code class="hljs less"><span class="hljs-selector-tag">yarn <span class="hljs-selector-tag">docs<span class="hljs-selector-pseudo">:build 或者:<span class="hljs-selector-tag">npm <span class="hljs-selector-tag">run <span class="hljs-selector-tag">docs<span class="hljs-selector-pseudo">:build</span></span></span></span></span></span></span></code>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

默认情况下,文件将会被生成在 `.vuepress/dist`,也可以通过 `.vuepress/config.js` 中的 `dest` 字段来修改.

以上步骤都成功以后,就可以在浏览器总看到页面了,接下来就是对页面进行布局

## 主题配置

本文是根据VuePress默认主题配置

### 1.首页

在docs文件夹下创建`.vuepress文件夹`和`README.md文件`。(如果以及有了就不要再新建)
根目录下的README.md文件可以当作首页,在文件中加入下面文字:

<pre><code class="hljs yaml"><span class="hljs-meta">---
<span class="hljs-attr">home: <span class="hljs-literal">true
<span class="hljs-attr">actionText: <span class="hljs-string">快速上手 <span class="hljs-string">→
<span class="hljs-attr">actionLink: <span class="hljs-string">/guide/install/install
<span class="hljs-meta">---</span></span></span></span></span></span></span></span></span></code>

可以根据自己的需要添加、删除、修改,这就完成了首页的布局
actionLink: /guide/install/install就是首页后要显示的下一个页面

接下来在docs文件夹中创建guide文件夹(根据自己的需要命名)。这个文件夹中放的是markdown文件,每一个markdown文件对应一个页面。至于页面之间的跳转和页面导航栏和侧边栏布局在config.js文件中设置。
VuePress 网站必要的配置文件是 .vuepress/config.js,它应该导出一个 JavaScript 对象:

<pre><code class="hljs java"><span class="hljs-keyword">module.<span class="hljs-keyword">exports = {
    title: <span class="hljs-string">'VuePress',
    description: <span class="hljs-string">'VuePress',
}</span></span></span></span></code>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

对于上述的配置,运行`yarn docs:dev`,你应该能看到一个页面,它包含一个页头,里面包含一个标题和一个搜索框。

### 2.导航栏

可以通过 `themeConfig.nav` 增加一些导航栏链接:

<pre><code class="hljs groovy"><span class="hljs-comment">// .vuepress/config.js
module.exports = {
<span class="hljs-symbol"> themeConfig: {
<span class="hljs-symbol"> nav: [
{<span class="hljs-string">text: <span class="hljs-string">'指南',<span class="hljs-string">link:<span class="hljs-string">'/guide/install/install'}
]
}
}</span></span></span></span></span></span></span></code>

当你提供了一个 items 数组而不是一个单一的 link 时,它将显示为一个 下拉列表

<pre><code class="hljs groovy">module.exports = {
<span class="hljs-symbol">  themeConfig: {
<span class="hljs-symbol">    nav: [
      {
<span class="hljs-symbol">        text: <span class="hljs-string">'Languages',
<span class="hljs-symbol">        items: [
          { <span class="hljs-string">text: <span class="hljs-string">'Chinese', <span class="hljs-string">link: <span class="hljs-string">'/language/chinese/' },
          { <span class="hljs-string">text: <span class="hljs-string">'Japanese', <span class="hljs-string">link: <span class="hljs-string">'/language/japanese/' }
        ]
      }
    ]
  }
}</span></span></span></span></span></span></span></span></span></span></span></span></span></code>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

### 3.侧边栏

想要使侧边栏(Sidebar)生效,需要配置 `themeConfig.sidebar`

<pre><code class="hljs java"><span class="hljs-comment">// .vuepress/config.js
<span class="hljs-keyword">module.<span class="hljs-keyword">exports = {
themeConfig: {
sidebar: [
{
title: <span class="hljs-string">'开发指南',
collapsable: <span class="hljs-keyword">false, <span class="hljs-comment">//是否展开
},
[<span class="hljs-string">'./guide/install/install',<span class="hljs-string">'安装'],
[<span class="hljs-string">'./guide/started/started',<span class="hljs-string">'快速上手'],
{
title: <span class="hljs-string">'组件',
collapsable: <span class="hljs-keyword">false
},
[<span class="hljs-string">'./guide/icon/icon',<span class="hljs-string">'icon'],
]
}
}</span></span></span></span></span></span></span></span></span></span></span></span></span></span></code>

可以省略 .md 拓展名,同时以 / 结尾的路径将会被视为 */README.md
如果想要显示地指定链接的文字,使用一个格式为 [link, text] 的数组。
具体配置可以根据官网配置:默认主题配置

这是浏览器显示效果:

1.png

现在页面基本也搭建完成,可以在页面之间进行切换。下一步是如何在markdown中使用vue组件,也就是在页面中展示自己的项目。

## 在markdown中使用Vue

.vuepress中创建components文件夹。
所有在 .vuepress/components 中找到的 *.vue 文件将会自动地被注册为全局的异步组件。

如果需要引入静态文件,可以在.vuepress下新建public文件夹,里面可以放静态文件。

因为本文的案例是展示Icon图标,所有引入了svg.jssvg.js可以在http://www.iconfont.cn/中获取,本文使用## symbol引用具体方法请访问官网。放在public文件夹中,可以在components文件夹中的组件引入。

这是docs文件夹目录结构

2.png

<pre><code class="hljs css">.
└─ <span class="hljs-selector-class">.vuepress
   └─ <span class="hljs-selector-tag">components
      ├─ <span class="hljs-selector-tag">demo-1<span class="hljs-selector-class">.vue
      └─ <span class="hljs-selector-tag">Icon
         └─ <span class="hljs-selector-tag">vi-icon<span class="hljs-selector-class">.vue</span></span></span></span></span></span></span></code>
1
2
3
4
5

可以直接使用这些组件在任意的 Markdown 文件中(组件名是通过文件名取到的):

<pre><code class="hljs javascript"><demo<span class="hljs-number">-1/>
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">Icon-vi-icon/> <span class="hljs-comment">//文件名和组件名之间同`-`连接</span></span></span></span></span></code>

完成这一步以后就可以在页面中看到自己的组件在页面中展示了,但是在运行下面命令进行打包的时候会报错:
报错原因参考官网文档:浏览器的 API 访问限制

<pre><code class="hljs less"><span class="hljs-selector-tag">yarn <span class="hljs-selector-tag">docs<span class="hljs-selector-pseudo">:build 或者:<span class="hljs-selector-tag">npm <span class="hljs-selector-tag">run <span class="hljs-selector-tag">docs<span class="hljs-selector-pseudo">:build</span></span></span></span></span></span></span></code>
1
2
3
4
5
6

解决这个问题只需要在使用Vue组件的`markdown`文件中使用`<ClientOnly></ClientOnly>`将组件包裹起来。如:

<pre><code class="hljs xml"><span class="hljs-tag"><<span class="hljs-name">ClientOnly>
<span class="hljs-tag"><<span class="hljs-name">Icon-vi-icon/>
<span class="hljs-tag"></<span class="hljs-name">ClientOnly></span></span></span></span></span></span></code>

注意:在markdown文件中如果需要给组件名缩进,不要用tab键,会被当做markdown语法解析。

浏览器效果图

3.png

到这一步,基本上可以在页面中展示自己的组件。下一篇将继续写如何通过Vue组件实现跟:Element相似的效果。
通过VuePress管理项目文档(二)

感谢支持原创技术分享
显示 Gitment 评论