VuePress 手摸手教你搭建一个类Vue文档风格的技术文档/博客
前言:
VuePress是尤大为了支持 Vue 及其子项目的文档需求而写的一个项目,VuePress界面十分简洁,并且非常容易上手,一个小时就可以将项目架构搭好。现在已经有很多这种类型的文档,如果你有写技术文档的项目的话,VuePress绝对可以成为你的备选项之一。
VuePress特性:
- 为技术文档而优化的 内置 Markdown 拓展
- 在 Markdown 文件中使用 Vue 组件的能力
- Vue 驱动的自定义主题系统
- 自动生成 Service Worker
- Google Analytics 集成
- 基于 Git 的 “最后更新时间”
- 多语言支持
- 默认主题包含:
建议先看一下官方文档
效果:
可能你会搭建出一个类似这样的文档:
搭建:
全局安装VuePress
yarn global add vuepress # 或者:npm install -g vuepress
新建文件夹
可以手动右键新建,也可以使用下面的命令新建文件夹:
mkdir project
项目初始化
进入到project
文件夹中,使用命令行初始化项目:
yarn init -y # 或者 npm init -y
将会创建一个package.json
文件,长这样子:
{"name": "project","version": "1.0.0","description": "","main": "index.js","scripts": {"test": "echo \"Error: no test specified\" && exit 1"},"keywords": [],"author": "","license": "ISC"
}
在project的根目录下新建docs文件夹:
这个文档将作为项目文档的根目录来使用:
mkdir docs
在docs文件夹下创建.vuepress
文件夹:
mkdir .vuepress
所有 VuePress 相关的文件都将会被放在这里
在.vuepress
文件夹下面创建config.js
:
touch config.js
config.js是VuePress必要的配置文件,它导出一个javascript对象。
你可以先加入如下配置:
module.exports = {title: 'Hello VuePress',description: 'Just playing around'
}
在.vuepress
文件夹下面创建public文件夹:
mkdir public
这个文件夹是用来放置静态资源的,打包出来之后会放在.vuepress/dist/的根目录。
首页(像VuePress文档主页一样)
在docs文件夹下面创建一个README.md
:
默认的主题提供了一个首页,像下面一样设置home:true
即可,可以把下面的设置放入README.md
中,待会儿你将会看到跟VuePress
一样的主页。
---
home: true
heroImage: /logo.jpg
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
---
ps:你需要放一张图片到public文件夹中。
我们的项目结构已经搭好了:
project
├─── docs
│ ├── README.md
│ └── .vuepress
│ ├── public
│ └── config.js
└── package.json
在 package.json
里添加两个启动命令:
{"scripts": {"docs:dev": "vuepress dev docs","docs:build": "vuepress build docs"}
}
启动你的VuePress:
默认是localhost:8080
端口。
yarn docs:dev # 或者:npm run docs:dev
构建:
build生成静态的HTML文件,默认会在 .vuepress/dist
文件夹下
yarn docs:build # 或者:npm run docs:build
基本配置:
最标准的当然是官方文档,可以自己的需求来配置config.js
。
可以参考一下我的config.js
的配置:
module.exports = {title: '网站标题',description: '网站描述',// 注入到当前页面的 HTML <head> 中的标签head: [['link', { rel: 'icon', href: '/favicon.ico' }], // 增加一个自定义的 favicon(网页标签的图标)],base: '/web_accumulate/', // 这是部署到github相关的配置 下面会讲markdown: {lineNumbers: true // 代码块显示行号},themeConfig: {sidebarDepth: 2, // e'b将同时提取markdown中h2 和 h3 标题,显示在侧边栏上。lastUpdated: 'Last Updated' // 文档更新时间:每个文件git最后提交的时间}
};
导航栏配置:
module.exports = {themeConfig: {nav:[{ text: '前端算法', link: '/algorithm/' }, // 内部链接 以docs为根目录{ text: '博客', link: 'http://obkoro1.com/' }, // 外部链接// 下拉列表{text: 'GitHub',items: [{ text: 'GitHub地址', link: 'https://github.com/OBKoro1' },{text: '算法仓库',link: 'https://github.com/OBKoro1/Brush_algorithm'}]} ]}
}
侧边栏配置:
侧边栏的配置相对麻烦点,我里面都做了详细的注释,仔细看,自己鼓捣鼓捣 就知道怎么搞了。
module.exports = {themeConfig: {sidebar:{// docs文件夹下面的accumulate文件夹 文档中md文件 书写的位置(命名随意)'/accumulate/': ['/accumulate/', // accumulate文件夹的README.md 不是下拉框形式{title: '侧边栏下拉框的标题1',children: ['/accumulate/JS/test', // 以docs为根目录来查找文件 // 上面地址查找的是:docs>accumulate>JS>test.md 文件// 自动加.md 每个子选项的标题 是该md文件中的第一个h1/h2/h3标题]}],// docs文件夹下面的algorithm文件夹 这是第二组侧边栏 跟第一组侧边栏没关系'/algorithm/': ['/algorithm/', {title: '第二组侧边栏下拉框的标题1',children: ['/algorithm/simple/test' ]}]}}
}
其他:
代码块编译错误:
像下面这段代码会导致编译错误,VuePress会去找里面的变量,把它编译成text:
{{}} 啦 {{}}
所以我们的代码块要以这种形式书写:
//```js
{{}} 啦 {{}} // 注释需要打开 这样vuepress会把这里面包裹的当成代码块而不是js
//```
并且这样也会让我们的代码高亮显示(下图第一个没有高亮,第二个有高亮),阅读体验更好:
自定义容器了解一下:
更改标题:
::: tip 替换tip的标题
这里是内容。
:::
其实文档里有,我这里只是提一下。
支持Emoji
文档中只提了支持Emoji,我在GitHub上找到了Emoji的列表,分享一下。
一个命令行发布到github上:
在 docs/.vuepress/config.js
中设置正确的 base:
如果你打算发布到 https://<USERNAME>.github.io/
,则可以省略这一步,因为 base 默认即是 "/"
。
如果你打算发布到 https://<USERNAME>.github.io/<REPO>/
(也就是说你的仓库在 https://github.com/<USERNAME>/<REPO>
),则将 base 设置为 "/<REPO>/"
。
module.exports = {base: '/test/', // 比如你的仓库是test
}
创建脚步文件:
在project
的根目录下,创建一个deploy.sh
文件:
#!/usr/bin/env sh# 确保脚本抛出遇到的错误
set -e# 生成静态文件
npm run docs:build# 进入生成的文件夹
cd docs/.vuepress/dist# 如果是发布到自定义域名
# echo 'www.example.com' > CNAMEgit init
git add -A
git commit -m 'deploy'# 如果发布到 https://<USERNAME>.github.io USERNAME=你的用户名
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master# 如果发布到 https://<USERNAME>.github.io/<REPO> REPO=github上的项目
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pagescd -
设置package.json:
{
"scripts": {
"d": "bash deploy.sh"
}
}
部署:
然后你每次可以运行下面的命令行,来把最新更改推到github
上:
npm run d
如果你对运行项目和构建项目的命令行觉得很烦,你也可以像我这么做:
"scripts": {"dev": "vuepress dev docs", // 本地运行项目 npm run dev"build": "vuepress build docs", // 构建项目 nom run build"d": "bash deploy.sh" // 部署项目 npm run d},
更多:
实际上VuePress的配置、用法还有很多,像还可以配置PWA,以及在markdown里面使用Vue组件等,这些功能我也还在摸索,所以大家一定要去看文档!
结语
上面已经写得尽可能详细了,我遇到的坑都写上去了。搭建起来确实很简单,心动不如行动,随手花一两个小时搭建一下又不吃亏,何乐而不为?
希望看完的朋友可以点个喜欢/关注,您的支持是对我最大的鼓励。
个人blog and 前端积累文档,如需转载,请放上原文链接并署名。码字不易,感谢支持!
如果喜欢本文的话,欢迎扫描关注我的订阅号,最新文章,面试题等都将第一时间发布在订阅号上。
以上2018.9.9
VuePress 手摸手教你搭建一个类Vue文档风格的技术文档/博客相关推荐
- mysql的单页应用框架搭建_采用vue+webpack构建的单页应用——私人博客MintloG诞生记...
介绍 项目地址:https://github.com/jrainlau/MintloG (特别乱,参考就好-_-|||) MintloG是我在五天之内完全由自己开发的私人博客,前端技术方案采用了vue ...
- 带你手摸手搭建vuepress站点
vuePress是什么? VuePress 俺简单介绍下,是国内有名大神的尤雨溪发布的全新基于 vue 静态网站的生成器,内置的有 webpack组件,可以拿来写文档,主要是md格式.做出的感觉就是简 ...
- 【万字长文】手摸手教你shell脚本编程
[万字长文]手摸手教你shell脚本编程 我写这篇文章的目的 前段时间参加了联创团队的春令营, 为期半个多月的春令营做了三个项目, 其中有一个项目是关于shell的, 当时完全没接触过shell脚本编 ...
- 微服务(三) 【手摸手带你搭建Spring Cloud】 Ribbon 什么是负载均衡?spring cloud如何实现负载均衡?ribbon负载均衡有几种策略?Ribbon是什么?
在上一章,我介绍了springcloud的eureka搭建.我们做了服务注册.最后我们还介绍了一些续约,失效剔除等参数配置.已经不需要再通过手动输入ip去访问服务,而是通过中心只需要通过服务名就可以获 ...
- 手摸手教你做动态壁纸
手摸手教你做动态壁纸 Android · jeasonwong · 于 5 天前发布 · 最后由 xingstarx 于 2 天前回复 · 440 次阅读 项目地址:https://github.co ...
- 手摸手产品研究院 | 玲珑沙龙-一个可以“撕逼”的女性文化社区
手摸手产品研究院是由PMCAFF发起的深度研究产品的产品经理精华小分队,旨在每天一起研究一款产品,并且由阿德老师手摸手指导写分析报告. 1-玲珑沙龙? 什么是玲珑沙龙,那些人在玩玲珑沙龙,为什么会玩? ...
- 每天研究一个产品,阿德老师“手摸手”带你写产品分析报告 |
作为一个产品经理,要高频地去把玩各种最新产品,所以我们想把那些对世界充满好奇心.勇于探索新鲜事物的产品经理都聚在一起.一起深入研究国内外最新/奇产品,一起发现有趣的事情,并把研究心得都整理成文章沉淀下 ...
- CSS —— 手摸手实现一个文字霓虹灯闪烁特效
CSS -- 手摸手实现一个文字霓虹灯闪烁特效 一.了解 text-shadow 属性 text-shadow 属性应用于阴影文本,属于 CSS3 的属性,默认值为 none. text-shadow ...
- 快应用之手摸手,跟我走(1)
快应用发布快两周啦.这两天有空,就捣鼓了一个快应用.整体感觉来说,交互很流畅,基本功能和组件都有.上手也很快.希望官网推广能做好.好了,话不多说,先上 gitHub (传送门) gankQuick-快 ...
最新文章
- c++调用python操作mongo
- 如何理解RESTful的幂等性
- 【C语言】%[修饰符] 格式字符
- Linux开启fileinfo扩展
- P2290-[HNOI2004]树的计数【组合数,Prufer序列】
- python入门100例题-这 100 道 Python 题,拿去刷!!!
- HDOJ 2037 今年暑假不AC
- SQLite: 注意日期查询中的“前空格”问题将引发错误查询!
- Crazy bubbles
- 使用d2rq把mysql转化为rdf_D2RQ数据导出
- [HAL]STM32F1光照度测量BH1750 串口输出
- 长白县积极建设精准扶贫云平台
- J8583CN解析ISO8583协议报文注意点
- 用“大数据”预防职务犯罪
- Python下openCV打开图片的几种方式/适应窗口大小
- 机器学习与R之朴素贝叶斯分类器
- 实验六 数组程序设计 → 张玉生《C语言程序设计实训教程》双色版 配套实验书答案 (纯手打, 仅供参考)
- 用ServletContext做一个简单的聊天室
- 年后胖三斤,减肥你准备好了吗
- 数字,字符,字符串转换
热门文章
- C#控制管理VisualSVN Server
- 用boost.signal实现多播委托
- GridView 控件的执行顺序
- 巧用SQL server的全局临时表防止用户重复登录
- 流行病学数据分析基础:识别和控制混杂
- 病例对照研究和队列研究详解
- linux卸载vs codeblocks,哪个适合linux? GNU make vs cmake vs codeblocks vs qmake
- opencv 图像增强_图像增强、锐化,利用 Python-OpenCV 帮你实现 4 种方法!
- 数学学习--最小二乘法案例剖析
- Cadence复用电路原理图及其PCB布局