Vuepress 2从0-1保姆级入门教程——安装流程篇
Vuepress2.X安装教程，教程以comet彗星文档为例教你一步步搭建自家的文档库
Vuepress 2 专栏目录【已完结】
1. 入门阶段
- Vuepress 2从0-1保姆级入门教程——环境配置篇
- Vuepress 2从0-1保姆级入门教程——安装流程篇
- Vuepress 2从0-1保姆级入门教程——文档配置篇
- Vuepress 2从0-1保姆级入门教程——主题与部署
2.进阶阶段
更新日志
- Markdown引用格式改为图片形式，更加醒目
- 图标数据更新
- 教程重制版更新，替换部分过时图片，添加路由说明
- 教程素材添加新版图标和源文档，方便找问题
- 修改文章病句
- 删除vuepress手动安装方式（对新手不友好）
- 更新到VuePress 2.0.0-rc.13版本，默认主题2.0.0-rc.35
- 引用块放大显示，避免文字不清晰
logo等静态文件：https://wwk.lanzouo.com/b04x8f3hg
密码：666
仓库：https://gitee.com/passwordgloo/vuepress2-tutorial
git clone git@gitee.com:passwordgloo/vuepress2-tutorial.git
cd vuepress2-tutorial
pnpm install
# 谨慎更新包
# pnpm docs:update-package
如果你按照教程一步步来，最后会得到下面的效果👇
一、安装Vuepress2
✅ 本教程以空白项目comet(彗星)为例，使用默认主题
✅ 如需换用其他主题，请跳转 Vuepress 2 主题与部署
✅ 本教程选用pnpm Node.js 包管理器，不清楚npm、yarn、pnpm区别的请参考程序员晚天的npm、yarn、pnpm优缺点
⚠️ 请确保Git、Node、Pnpm安装完毕，如果不清楚环境配置，移步这里Vuepress 2.X 环境配置篇
❌ 请勿在驱动器根目录运行，比如D:\ ，会提示没有权限
（一）自动化安装
pnpm create vuepress comet
- 非常方便，只需要一行命令
- 已有空仓库直接执行下列代码会提示文件夹非空，可以在执行完后把空仓库📁.git复制过去
填y同意预览，点击链接，此时显示VuePress 2 介绍页
Vscode打开comet文件夹，新建.gitignore文件（git忽略目录）
#ide
*.DS_Store
.idea
.vscode
#npm
package-lock.json
yarn.lock
#build result
dist
lib
docs/.vuepress/.temp
docs/.vuepress/.cache
docs.vuepress/dist
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
# Runtime config
pids
*.pid
*.seed
*.pid.lock
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release
# Dependency directories
node_modules
# Optional npm cache directory
.npm
# Optional eslint cache
.eslintcache
# Optional REPL History
.node_repl_history
# Output of 'npm pack'
*.tgz
# Yarn Integrity file
.yarn-integrity
# dotenv environment variables file
.env
#lerna-changelog
.changelog
#vscode history extension
.history
此时文件目录如下，注意.gitignore文件Windows用户正常显示，Ubuntu和Mac默认隐藏.开头的文件
📂 docs 存放文档和主题配置文件
📁 node_modules(node模块) 依赖包位置，定制化需求时再动
🔖 package.json记载包的安装版本，请参考我有一棵树的关于package.json 和package-lock.json了解详情
（二）预览
pnpm docs:dev
使用pnpm docs:dev预览时，会生成缓存文件(.cache,temp)方便下次更快预览，但是下次作出重大调整后，如果还是之前的效果，请使用下列指令，作用相当于先清除缓存再预览
pnpm docs:clean-dev
框架搭建
一、Package.json【可选】
Vscode打开项目文件夹，编辑package.json
✔️ 以下内容可选，SEO需要这些,不需要的话可以跳过
"keywords": [
"关键词1",
"关键词2",
"关键词3"
],
"author": "作者名字",
"homepage": "你的主页地址",
"repository": {
"type": "git",
"url": "你的仓库地址"
},
二、搭建文档首页
（一）路由
1. 路由解释
好多人都会忽略这一块，但请你一定要过一下，不然后面的文件路径你看不明白
这里的路由不是计算机网络中的路由，它是单页应用路径管理器。Vuepress里每一个Markdown文件借助markdown-it转换为浏览器熟悉的单个html文件，使用Vue自家的vue router规划好路由路径，浏览器就能根据地址找到对应文件。
咦，HTML中a标签不也能实现页面跳转吗？Vue干嘛要折腾出一个vue-router？因为a标签每执行一次都会重新渲染一次页面，白白消耗DOM性能，vue学聪明了，按照模块组件化设计，我按需渲染指定的组件(component)，避免了重复渲染问题，这种优势在本地页面视觉效果不明显，但是放在云端，你使用a标签点击一个页面，出现了视觉”闪烁“效果，用户体验不就没了
2.相对路径与路由路径关系
Vuepress使用相对路径描述文件位置，再转化为路由路径(这个我们不用管），下表展示了二者的对应关系：
| 相对路径 | 路由路径 |
|---|---|
| /README.md | / |
| /index.md | / |
| /about.md | /about.html |
| /vue/README.md | /vue/ |
相对路径里README.md和index.md都会转化成index.html，两者同一层级时会冲突的
换句话说，README.md和index.md不能在一个文件夹共存
3.相对路径父目录
相对路径前面的/不同情形下指代的父级目录是不同的
| 情形 | 父目录 |
|---|---|
| markdown文件 | 默认是📁docs，配置里可自定为其他 |
| 音乐、图标、附件等静态文件 |  |
| 导航栏、侧边栏语言设置、vuepress语言设置，主题语言设置 | /指当前语言/en/指📂docs里的📁en/zh/指📂docs里的📁zh（en和zh名字任取） |
（二）文档首页
1️⃣ 在📁docs文件夹内部新建README.md，自动化安装的用户直接替换原先内容
2️⃣ Markdown文件开头可以设置YAML Frontmatter。代码两端使用---隔开，你可以理解为当前文档的属性信息，后面是自己写的内容，遵循Markdown语法
---
home: true
heroImage: /comet.png
heroText: 彗星文库
tagline: 繁星似海 熠熠生辉
actions:
- text: 博客
link: https://blog.csdn.net/passwordgloo
type: primary
- text: 关于
link: about.md
type: secondary
features:
- title: 笔记
details: Markdown语言，简洁高效记录每一刻
link: https://www.baidu.com
- title: 博客
details: 干净整洁的博客，易于存档文件
- title: 文档
details: 在线个人文档，创作中意的文档
footer: MIT Licensed | Copyright © 2020-present Passwordgloo
---
| 名称 | 含义 |
|---|---|
| home | 判断是否是首页 |
| heroImage | 首页logo图，支持svg、png、gif、jpg |
| heroText | 首页标题 |
| tagline | 首页标语 |
| actions | 按钮，text和link可以多个 |
| text | 按钮文字 |
| link | 按钮链接，子版块文件夹名 |
| features | 文档分栏，title和details数量自定 |
| footer | 文档底部板块 |
3️⃣ 📁.vuepress文件夹内新建📁public文件夹，放入comet.png和favicon.ico文件
（三）预览效果
🔔 终端使用Ctrl+C🉑停止前面的预览
pnpm docs:dev
🎯 点击右上角太阳图标，查看深色模式
三、子版块
（一）定义
子版块是除首页外其他内容的版块
子版块首页还是README.md文件
不同子版块和多语言使用文件夹分隔，避免相互干扰
在📁docs文件夹新建文件夹存放子版块，名字任意不重复，不区分字母大小写，数量无要求，不推荐中文命名，容易报错
（二）YAML Frontmatter
与文档首页一样，子版块Markdown 文件可以包含一个 YAML Frontmatter 。Frontmatter 必须在 Markdown 文件的顶部，并且被包裹在一对三短划线中间
默认主题提供的选项如下，属性值都为true（启用）/ false（不启用）
| 英文名 | 中文解释 | 备注 |
|---|---|---|
| navbar | 导航栏 | 默认启用 |
| sidebar | 侧边栏 | 可设置sidebar:heading本页面启用 |
| lastUpdated | 最近更新时间 | git push的时间 |
| editLink | 编辑本页功能 | |
| contributors | 贡献者 | 有需要就加 |
（三）示例
docs文件夹新建⭐️about.md
---
sidebar: heading
---
# 了解我
 
 
 
 
<iframe frameborder="no" border="0" marginwidth="0" marginheight="0" width=100% height=110 src="//music.163.com/outchain/player?type=0&id=7113076622&auto=1&height=90"></iframe>
## 教程使用
访问[蓝奏云](https://wwk.lanzouo.com/b04x8f3hg),密码666
## 项目用途
* 归档个人学习经验
* 留下自己学习印迹
* 启迪他人思想火花
## 联系信息
- [Github](https://github.com/passwordgloo)
- [Gmail](mailto:flyigloo@gmail.com)
- [163邮箱](mailto:passwordgloo@163.com)
重新进入首页，点击关于
在 Vuepress 2 文档配置篇我们将完善config.ts，添加logo、导航栏、侧边栏
前往低代码交流专区
更多推荐
14
0- 0
已为社区贡献3条内容
所有评论(0)