手把手使用VuePress搭建Element的组件库文档官网 |
您所在的位置：网站首页 › 组件element官网 › 手把手使用VuePress搭建Element的组件库文档官网 |
手把手使用VuePress搭建Element的组件库文档官网
|
本教程具有视频版本，见B站《VuePress搭建Element组件库文档》 为什么要使用VuePress？社区里面有很多优秀的文档工具可以供我们前端程序员选择，例如Gitbook、Hexo、Docusaurus。就个人使用而言，体验最好的文档工具是Docusaurus。
Docusaurus具有配置简单，目录结构合理、Markdown渲染配置灵活等一系列的优点。但对于Vue的开发者不太友好的是，Docusaurus是基于React的，如果你想在其中使用Vue的写法和渲染Vue组件会变得十分困难。所以如果你是Vue的开发者，在编写Vue相关组件文档的时候，个人还是推荐使用官方的VuePress。 下面的教程会使用VuePress生成类似Element的组件文档库，包括Vue组件展示、示例代码展示、自定义主题等常用功能。 安装 创建项目 vuepress-element-doc mkdir vuepress-element-doc && cd vuepress-element-doc 初始化npm包管理并在package.json 中新增脚本 npm init -y // package.json "scripts": { "dev": "vuepress dev docs","build": "vuepress build docs" }, 安装 VuePress + Element npm install vuepress element-ui --registry=https://registry.npm.taobao.org因为我们要做的是Element的组件文档页，所有这里顺便安装一下Element。你如果需要展示你自己的组件库，那么安装或引人自己的组件库的js和css即可。 创建首页 新建首页.md文件新建 docs/README.md --- home: true heroImage: https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/element-index.png heroText: Element features: - title: 一致性 Consistency details: 与现实生活一致：与现实生活的流程、逻辑保持一致，遵循用户习惯的语言和概念 - title: 反馈 Feedback details: 通过界面样式和交互动效让用户可以清晰的感知自己的操作 - title: 效率 Efficiency details: 界面简单直白，让用户快速识别而非回忆，减少用户记忆负担。 footer: by饿了么 --- ### 设计原则
一致性 Consistency 
反馈 Feedback 
效率 Efficiency 
可控 Controllability 这个README.md中一共有三种语法： YAML: 顶部以 --- 包裹起来的是YAML语法的Front Matter，这个语法必须位于.md的顶部，是可选的。 Markdown: 其中 ### 设计原则 部分是Markdown语法，相信大家都很熟悉。 HTML: 最后是我们熟悉的HTML语法，总所周知，在 .md 中是可以使用HTML语法的。备注：docs/README.md中的图片地址是放到OSS上的地址，因为这样更方便使用。当然你也可以使用本地的公共文件，具体见Vuepress/静态资源/公共文件。 创建配置文件新建 docs/.vuepress/config.js ，填入基本的配置信息。注意，这个文件是VuePress最核心的一个文件，有着丰富的配置项。 module.exports = { theme: '',title: 'VuePress + Element',description: 'VuePress搭建Element的组件库文档教程示例代码',base: '/',port: '8080',themeConfig: {},head: [],plugins: [],markdown: {} } 启动项目使用命令运行VuePress，查看效果 npm run dev浏览器访问 localhost:8080 ，如果没有意外，我相信你已经能够在页面上看到如下的效果了，这个页面就是我们在README.md 这个文件中所编写的YAML + Markdown + HTML的整体效果。
创建 /docs/comps/README.md,填入内容。这里模仿的是Element官网的安装页面。 # 安装 ## npm安装 推荐使用 npm 的方式安装，它能更好地和 webpack 打包工具配合使用。 npm i element-ui -S ## CDN 目前可以通过 unpkg.com/element-ui 获取到最新版本的资源，在页面上引入 js 和 css 文件即可开始使用。创建 /docs/comps/select.md，填入内容。创建两个文件是方便我们之后设置文档侧边栏,这里模仿的是Element官网的选择器组件页面。 # Select 选择器 当选项过多时，使用下拉菜单展示并选择内容。 ## 基本用法 适用广泛的基础单选 配置顶部导航栏在/docs/.vuepress/config.js 中配置顶部导航栏的配置字段 themeConfig.nav。代码如下： module.exports = { theme: '',themeConfig: { // 新增代码 nav: [ // 配置顶部导航栏 { text: '首页',link: '/' },{ text: '组件',link: '/comps/' } ] },markdown: {} } 配置组件页文档的侧边栏在/docs/.vuepress/config.js 中配置顶部导航栏的配置字段 themeConfig.sidebar。代码如下： module.exports = { theme: '',themeConfig: { nav: [ { text: '首页',link: '/comps/' } ],sidebar: { // 配置侧边栏部分 '/comps/': ['/comps/','/comps/select.md'] } },markdown: {} }此时我相信你就能够在浏览器上看到这样的页面了，是不是有一点Element文档的味道了。
可是到目前为止，我们还没有引入Element的组件部分，既然是一个组件库，我们自然希望实现像Element这样，上面有组件的展示，下面是示例的代码。这一部分我们就来看看如何实现这个效果吧
这里我们会使用到一个 vuepress-plugin-demo-container 这个插件，使用以下命令安装 npm install vuepress-plugin-demo-container然后在/docs/.vuepress/config.js文件中配置上该插件 module.exports = { // ... plugins: ['demo-container'],// 配置插件 markdown: {} } 认识enhanceApp.js你有没有想过我们平时在项目里面使用Element，需要在 app.js 中引入Element，并调用 Vue.use(Element) 才能够在Vue中使用Element的组件，那么我们如果想在VuePress中使用Element，我们需要去哪里编写这段代码呢？ 此时我们需要认识一个新的文件enhanceApp.js，它算是VuePress中仅此于config.js 第二重要的文件了，当你想做一些Vue应用级别的配置时，就需要在这个文件里面配置。让我们在新建该文件吧：/docs/.vuepress/enhanceApp.js。 import ElementUI from 'element-ui'; import 'element-ui/lib/theme-chalk/index.css'; export default async ({ Vue }) => { if (typeof process === 'undefined') { Vue.use(ElementUI) } } 引入Element组件接下来我们在刚才创建的/docs/comps/select.md中使用Element试试看吧。使用下面的内容替换原有的内容吧。 # Select 选择器 当选项过多时，使用下拉菜单展示并选择内容。 ## 基本用法 适用广泛的基础单选 ::: demo 适用广泛的基础单选 ```html export default { data() { return { options: [{ value: '选项1',label: '黄金糕' },{ value: '选项2',label: '双皮奶' }],value: '' } } } \```(注意：需要去掉前面的‘\’！！！) :::如果一切顺利的话，我相信你此时应该能够看到以下的效果了：
到目前未知，组件库的基本框架就已经搭建完成了，剩下的就是填充内容并最终部署。现在我们来讲一下部署环节。 执行部署命令还记得我们之前在 package.json 中配置VuePress部署脚本的"build": "vuepress build docs"吗？所以我们只需要执行以下命令即可 npm run build查看文件，你会发现此时/docs/.vuepress/dist 这个文件多了出来，dist 目录就是我们的最终部署目录。 ├── docs │ ├── .vuepress │ │ ├── config.js │ │ ├── dist │ │ │ ├── 404.html │ │ │ ├── assets │ │ │ │ ├── css │ │ │ │ │ └── 0.styles.262ade0c.css │ │ │ │ ├── fonts │ │ │ │ │ ├── element-icons.535877f5.woff │ │ │ │ │ └── element-icons.732389de.ttf │ │ │ │ ├── img │ │ │ │ │ └── search.83621669.svg │ │ │ │ └── js │ │ │ │ ├── 2.ae254118.js │ │ │ │ ├── 3.c4b624da.js │ │ │ │ ├── 4.8c48097d.js │ │ │ │ ├── 5.a4fed9a4.js │ │ │ │ ├── 6.efea7d5a.js │ │ │ │ ├── 7.fc05164e.js │ │ │ │ ├── 8.8ee7961b.js │ │ │ │ ├── 9.e8d922fc.js │ │ │ │ └── app.90733c82.js │ │ │ ├── comps │ │ │ │ ├── index.html │ │ │ │ └── select.html │ │ │ └── index.html │ │ └── enhanceApp.js │ ├── README.md │ └── comps │ ├── README.md │ └── select.md ├── package-lock.json └── package.json 使用Web Server部署只需把root目录指向/docs/.vuepress/dist/就可以部署到服务，这里我们使用了本机的MAMP的Apache用做Web Server。当然你也可以使用nginx或者任何你喜欢的服务器进行部署。
此时输入Web Server所配置的端口名称，就能看见已经部署成功了
|
【本文地址】
今日新闻 |
推荐新闻 |