百家饭团队开发的百家饭OpenAPI平台是用vuepress2.0搭建的,搭建的时候不知道2.0还处在beta状态,所以导致后来踩了一些坑,使用过程中vuepress2.0也从2.0.0-beta.18升到了2.0.0-beta.48,有很多的变化,所以想写一个教程介绍一下vuepress2.0的情况以及使用经验。
大致计划写这些内容吧:
- vuepress介绍、选型原因及使用感受(先介绍一下自己用的情况吧)
- vuepress2.0使用(搭建一个vuepress支撑的网站)-第一部分
- vuepress2.0使用(搭建一个vuepress支撑的网站)-修改默认模板配置
- vuepress2.0使用(搭建一个vuepress支撑的网站)-详细配置默认模板
- vuepress2.0使用(搭建一个vuepress支撑的网站)-md文件的玩法
- vuepress2.0使用(扩展默认主题)- 准备及扩展页面组件
- vuepress2.0使用(扩展默认主题)- 提供更多页面模板并引入ElementUI
- vuepress2.0使用(扩展默认主题)- 扩展MD页面功能(Section扩展及自定义语法)
- vuepress2.0使用(扩展默认主题)- 引入百度搜索支持及其他库的引用
- 编写vuepress主题(自定义自己的框架,开发复杂程序)
- vuepress2.0使用——编译及站点部署
- vuepress2.0当前的状态(版本变化,方便大家升级,占位中,未书写)
- 更多读者发起话题点击这里进专题查看,就不更新标题了
这里先给搜索进来的同学提个醒:凡是网上搜索到需要修改clientAppEnhance.js 文件的教程都已经过时,最新版本已不再使用。另外说个题外话,我查了下,我为数不多的搜索关键词里面,vuepress的占了大部分,这里感谢大家的关注,这个教程肯定有不合理的地方,如果有任何需要帮助的,大家都可以留言,我尽力解答。
使用vuepress 2.0搭建一个简单站点
这一篇我们就开始使用vuepress来搭建一个简单的网站,我们先按照官网的说明,执行以下步骤,执行前请先创建一个文件夹,进入文件夹执行以下步骤
# install in your project
yarn add -D vuepress@next
# 在当前文件夹创建一个README.md文件,利用命令输入内容:# Hello VuePress
echo '# Hello VuePress' > README.md
# start writing,这一步执行就会运行测试服务了,下一步是用于打包的,可以暂时不执行
yarn vuepress dev
# build to static files
yarn vuepress build
很遗憾,我们测试用的2.0.0-beta.49版本打开是这样的。
很诡异是吧,如果你也遇到这个问题,请用编辑器打开刚才第二步操作生成的README.md文件,将其用utf-8编码进行重新保存
然后应该就没有问题了:
这个页面就是vuepress默认主体的页面结构了,左边是一个文章列表,右边是文件详情。
上面是一个工具栏。
我们可以尝试编辑README.md,那新增加的内容就会在右边呈现出来。
稍微解释一下:为什么是README.md文件?vuepress默认认为一个目录的默认文档是index.md或者README.md,既然这是网站首页,那就是要去寻找当前目录下的index.md或者README.md,你可以尝试把README.md改成index.md是一样的效果,但是改成doc1.md就会报404
其他初始化步骤
然后我们按照官方文档执行一些其他操作,
1)在package.json增加操作入口
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
注意,这个地方官方文档的快速上手页面实际和首页有些冲突,首页的执行测试服务器执行的是:
yarn vuepress dev
但是这里添加的是vuepress dev docs,是因为快速上手页面是在docs目录下创建的README.md文件,首页是在根目录下创建的,所以其实你现在有3个方案:
a. 创建一个docs目录,把刚才创建的README.md移动过去
b. 把上述命令中的docs去掉,改成:
{
"scripts": {
"docs:dev": "vuepress dev",
"docs:build": "vuepress build"
}
}
c. 使用其他任意名称的子目录,只要script里面对应上就行
{
"scripts": {
"docs:dev": "vuepress dev 子目录名",
"docs:build": "vuepress build 子目录名"
}
}
个人建议用方案a,这样所有文档都在一个子目录里,从我们的经验来看,因为百家饭平台是Golang+vuepress的方案,因此,根目录就作为golang标准结构,docs作为vuepress的部分,互不冲突。下面的描述假设采用的方案a。
2)配置.gitignore, 增加以下几行:
node_modules
.temp
.cache
基本初步的搭建就完成了。