首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >VuePress

VuePress

作者头像
庞小明
发布2019-05-25 18:03:28
1.2K0
发布2019-05-25 18:03:28
举报
文章被收录于专栏:pangguomingpangguoming

VuePress

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

全局安装

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

# 新建一个 markdown 文件
echo '# Hello VuePress!' > README.md

# 开始写作
vuepress dev .

# 构建静态文件
vuepress build .

注意 :vuepress dev .vuepress build .后面的.

在现有项目中安装

# 将 vuepress 作为一个本地依赖安装
yarn add -D vuepress 或者:npm install -D vuepress

# 新建一个 docs 文件夹
mkdir docs

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

# 开始写作
npx vuepress dev docs

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

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

开始写作

yarn docs:dev 或者:npm run docs:dev

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

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

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

yarn docs:build 或者:npm run docs:build

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

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

主题配置

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

1.首页

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

---
home: true
actionText: 快速上手 →
actionLink: /guide/install/install
---

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

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

module.exports = {
    title: 'VuePress',
    description: 'VuePress',
}

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

2.导航栏

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

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [       
           {text: '指南',link:'/guide/install/install'}
        ]
  }
}

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

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        items: [
          { text: 'Chinese', link: '/language/chinese/' },
          { text: 'Japanese', link: '/language/japanese/' }
        ]
      }
    ]
  }
}

3.侧边栏

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

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
        {
            title: '开发指南',
            collapsable: false, //是否展开
        },
        ['./guide/install/install','安装'],
        ['./guide/started/started','快速上手'],
        {
            title: '组件',
            collapsable: false
        },
        ['./guide/icon/icon','icon'],
    ]
  }
}

可以省略 .md 拓展名,同时以 / 结尾的路径将会被视为 */README.md 如果想要显示地指定链接的文字,使用一个格式为 [link, text] 的数组。

这是浏览器显示效果:

1.png
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
2.png
.
└─ .vuepress
   └─ components
      ├─ demo-1.vue
      └─ Icon
         └─ vi-icon.vue

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

<demo-1/>
<Icon-vi-icon/> //文件名和组件名之间同`-`连接

完成这一步以后就可以在页面中看到自己的组件在页面中展示了,但是在运行下面命令进行打包的时候会报错:

yarn docs:build 或者:npm run docs:build

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

<ClientOnly>
  <Icon-vi-icon/>
</ClientOnly>

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

浏览器效果图

3.png
3.png
本文参与 腾讯云自媒体分享计划,分享自作者个人站点/博客。
原始发表:2019-02-03 ,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • VuePress
    • 全局安装
      • 在现有项目中安装
        • 主题配置
          • 1.首页
          • 2.导航栏
          • 3.侧边栏
        • 在markdown中使用Vue
        领券
        问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档