通过VuePress管理项目文档(一)
VuePress
相关链接
完整的Vue组件代码以及完整的文档,仅适用于个人参考学习:
文档预览地址:预览链接
使用VuePress
编辑文档的代码访问:组件文档
完整代码:组件代码
Vue组件开发
这篇文章主要是记录自己在使用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]
的数组。
具体配置可以根据官网配置:默认主题配置
这是浏览器显示效果:
现在页面基本也搭建完成,可以在页面之间进行切换。下一步是如何在markdown
中使用vue组件,也就是在页面中展示自己的项目。
在markdown中使用Vue
在.vuepress
中创建components
文件夹。
所有在 .vuepress/components
中找到的 *.vue
文件将会自动地被注册为全局的异步组件。
如果需要引入静态文件,可以在.vuepress
下新建public
文件夹,里面可以放静态文件。
因为本文的案例是展示Icon图标,所有引入了svg.js
,svg.js
可以在http://www.iconfont.cn/中获取,本文使用symbol引用
具体方法请访问官网。放在public
文件夹中,可以在components
文件夹中的组件引入。
这是docs文件夹目录结构
.
└─ .vuepress
└─ components
├─ demo-1.vue
└─ Icon
└─ vi-icon.vue
可以直接使用这些组件在任意的 Markdown 文件中(组件名是通过文件名取到的):
<demo-1/>
<Icon-vi-icon/> //文件名和组件名之间用`-`连接
完成这一步以后就可以在页面中看到自己的组件在页面中展示了,但是在运行下面命令进行打包的时候会报错:
报错原因参考官网文档:浏览器的 API 访问限制
yarn docs:build 或者:npm run docs:build
解决这个问题只需要在使用Vue组件的markdown
文件中使用<ClientOnly></ClientOnly>
将组件包裹起来。如:
<ClientOnly>
<Icon-vi-icon/>
</ClientOnly>
注意:在markdown文件中如果需要给组件名缩进,不要用tab
键,会被当做markdown
语法解析。
浏览器效果图
到这一步,基本上可以在页面中展示自己的组件。下一篇将继续写如何通过Vue组件实现跟:Element相似的效果。
通过VuePress管理项目文档(一)的更多相关文章
- 通过VuePress管理项目文档(二)
通过vue组件实现跟:Element相似的效果.需要在VuePress网站中将自己的项目中的Vue组件运行结果展示在页面中. 至于如何将组件在VuePress网站中展示请参考:https://segm ...
- 【原创】利用doxygen来管理项目文档或注释
一.doxygen应用场景: doxygen可以用来管理目前主流的编程语言的注释而形成文档系统.(包括C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Py ...
- Git与GitHub学习笔记(六)使用 Github Pages 管理项目文档
前言 你可能比较熟悉如何用 Github Pages 来分享你的工作,又或许你看过一堂教你建立你的第一个 Github Pages 网站的教程.近期 Github Pages 的改进使得从不同的数据源 ...
- [课程分享]IT软件项目管理(企业项目甘特如是评价、维护管理、文档管理、风险管理、人力资源管理)
[课程分享]IT件项目管理(企业项目甘特图案例评价.维护管理.文档管理.风险管理.人力资源管理) 对这个课程有兴趣的朋友能够加我的QQ2059055336和我联系 课程讲师:丁冬博士 课程分类:Jav ...
- vuepress+gitee 构建在线项目文档
目录 快速入门 在现有vue项目中安装本地开发依赖vuepress 在现有vue项目根目录下创建docs目录 创建并配置文档首页内容 运行,查看效果 可能会出现vue和vue-server-rende ...
- Atitit. 项目文档目录大纲 总集合 v2
Atitit. 项目文档目录大纲 总集合 v2 -----Atitti.原有项目源码的架构,框架,配置与环境说明 v3 q511 -----Atitit.开发环境 与 工具 以及技术框架 以及 注意 ...
- PowerDesigner(九)-模型文档编辑器(生成项目文档)(转)
模型文档编辑器 PowerDesigner的模型文档(Model Report)是基于模型的,面向项目的概览文档,提供了灵活,丰富的模型文档编辑界面,实现了设计,修改和输出模型文档的全过程. 模型文 ...
- 使用Mkdocs构建你的项目文档
使用Mkdocs构建你的项目文档 环境搭建 安装必需软件 作者是在windows下安装的,如果是linux或mac用户,官网有更详细的安装说明. windows 10 x64 当然还有广大的windo ...
- MkDocs项目文档生成器
简介 安装 我的配置 Chocolatey 简介 - Windows的包管理器 官方网址 安装 注意事项 Python 简介 安装 Pip 简介-Python的包管理器 升级 MkDocs的安装 使用 ...
随机推荐
- Redis协议规范(RESP)
Redis 即 REmote Dictionary Server (远程字典服务): 而Redis的协议规范是 Redis Serialization Protocol (Redis序列化协议) 该协 ...
- 自定义GridControl编辑器
本文版权归博主 惊梦无痕 所有,欢迎转载,但须保留此段声明,并给出原文链接,谢谢合作.SourceLink 鉴于网上的针对GridControl的一些代码比较凌乱,且功能分散,故将整理过的代码分享出来 ...
- JavaScript小记二则:接上一节:用.net写Textbox控件关于数字的判断的另一则方法
方法二.通过写JS进行判断控制输入的只能为数字,源码如下: <!DOCTYPE html> <html> <body> <h1></h1> ...
- 解析高德地图api获取省市区,生成最新三级联动sql表
前言: 最近项目中用到了全国省市区三级信息,但是网上找到的信息都是比较旧的信息.与现在最新的地区信息匹配不上.后来想到高德地图上可能有这些信息.所以解析了一下api接口,生成了相关省市区的sql信息. ...
- jsp内置对象-response对象
一.概念 隐含对象response是javax.servlet.HttpServletResponse接口实现类的对象.response对象封装了JSP产生的响应,用于响应客户端的请求,向客户端输出信 ...
- 使用VC建立网络连接并访问网络资源
目录 1. 提出问题 2. 解决方案 1. 提出问题 在windows下可以通过系统操作,将局域网的资源映射到本地,从而实现像本地数据一样访问网络资源.实际上这些步骤也可通过代码调用win32函数实现 ...
- mapfile中关于栅格数据的processing项说明
mapfile是MapServer中地图的配置文件,规定了地图的源数据.投影.样式等一系列信息.用MapServer发布影像地图,需要用以下processing项设置地图的风格样式. BANDS=re ...
- 阅读笔记:基础知识(Java篇)
1. GC机制(垃圾回收机制) 找到垃圾的方法:引用计数法.可达性分析法 回收垃圾的方法:标记清除算法.复制算法.标记整理法.分代算法 2. JVM内存划分 线程私有:程序计数器.JVM虚拟机栈.本地 ...
- SQLServer之数据库行锁
行锁使用注意事项 1.ROWLOCK行级锁确保在用户取得被更新的行,到该行进行更新,这段时间内不被其它用户所修改.因而行级锁即可保证数据的一致性,又能提高数据操作的并发性. 2.ROWLOCK告诉SQ ...
- 利用ZYNQ SOC快速打开算法验证通路(6)——LWIP实现千兆TCP/IP网络传输
一.前言 之前ZYNQ与PC之间的网络连接依赖于外接硬件协议栈芯片,虽然C驱动非常简单,但网络带宽受限.现采用LWIP+PS端MAC控制器+PHY芯片的通用架构.关于LWIP库,已经有很多现成的资料和 ...