这篇文章主要是记录自己在使用 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
- heroImage: /hero.PNG
actionText: 快速上手 →
- 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.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'],
- ['./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 http://element-cn.eleme.io/#/zh-CN/component/icon 相似的效果.
来源: https://www.cnblogs.com/qfstudy/p/10061771.html