您现在的位置是:网站首页> 内容页

通过vuepress管理项目文档(一)

  • 金沙国际唯一官网登录
  • 2019-04-23
  • 116人已阅读
简介这篇文章主要是记录自己在使用vuepress过程中所遇到的问题以及如何一步一步的解决问题。安装vuepress前,请确保你的Node.js版本>=8全局安装#安装yar

这篇文章主要是记录自己在使用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: trueheroImage: /hero.pngactionText: 快速上手 →actionLink: /zh/guide/features:- title: 简洁至上 details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。- title: Vue驱动 details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。- title: 高性能 details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。footer: MIT Licensed | Copyright © 2018-present Evan You---

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

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

module.exports = { title: "Hello VuePress", description: "Just playing around"}

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

2.导航栏

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

// .vuepress/config.jsmodule.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.jsmodule.exports = { themeConfig: { sidebar: [ { title: "开发指南", collapsable: false, //是否展开 }, ["./guide/install/install","安装"], ["./guide/started/started","快速上手"], { title: "组件", collapsable: false }, ["./guide/icon/icon","icon"], ["./guide/button/button","button"], ] }}

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

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

在markdown中使用Vue

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

.└─ .vuepress └─ components ├─ demo-1.vue └─ Foo └─ demo-2.vue

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

<demo-1/><Foo-demo-2/> //文件名和组件名之间同`-`连接

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

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

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

<ClientOnly> <Foo-demo-2/></ClientOnly>

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

到这一步,基本上可以在页面中展示自己的组件。下一篇将继续写如何通过vue组件实现跟Element相似的效果。

, 1, 0, 9);

文章评论

Top