admin管理员组文章数量:1618700
Vuepress
- VuePress简介
- 安装Vuepress
- 全局安装
- 局部安装
- 创建工程
- 部署到xxx.github.io
- dev 和 build的个人理解
- package.json配置
- deploy-gh.sh 配置
- config.js 配置
- 执行脚本部署
- 功能配置
- 导航栏链接
- 定制侧边栏配置
- 最后更新时间
- 侧边栏显示层级
- 语言配置
- Head标签logo
- Git仓库和编辑链接
- 代码块显示行号
- 首页部署
- Makedown相关语法学习
- 跳转
- emoji大全
- 自定义容器
- Git相关问题
- .gitignore配置
- github ssh密钥配置
- 配置ssh
VuePress简介
VuePress 是一款使用 Vue 驱动的静态网站生成器,是 Vue 的作者 Evan You 为了方便文档的编写而开发的。
- 默认主题与 Vue 官方文档一致
- 简洁,少配置,高性能
- Markdown 专为技术文档提供拓展
- 自带 PWA
- 自定义主题,可定制程度完全由自己决定
- VuePress中文网
- Vuepress
安装Vuepress
可以选择全局安装
或者局部安装
(选一个版本安装即可,使用 yarn 或 npm 都可以)npm
是在nodejs
环境安装好后就可以使用
全局安装
以后所有项目都会直接调用
yarn add -g vuepress # npm install -g vuepress
局部安装
只针对当前工程,安装包会下载到当前工程下,选择局部安装的直接跳过从创建工程
开始看
yarn add -D vuepress # npm install -D vuepress
创建工程
-
创建并进入一个新目录,win系统直接右键创建文件夹即可,工程名随意
mkdir vuepress-starter && cd vuepress-starter
-
使用你喜欢的包管理器进行初始化
yarn init # npm init
-
将
VuePress
安装为本地依赖(局部安装),我们已经不再推荐全局安装VuePress
yarn add -D vuepress # npm install -D vuepress
-
创建你的第一篇文档,在创建第一篇文档的时候,有必要梳理下
vuepress
的文件结构. ├── docs │ ├── .vuepress │ │ ├── public │ │ └── config.js │ │ │ └── README.md │ └── package.json
docs
是入口,名字不可替代(请勿自定义)package.json
初始化后生成的(即npm init)- 上述名字均不可更改,请确保项目下文件夹名一致
- win系统用户可通过正常界面操作
mkdir docs && echo '# Hello VuePress' > docs/README.md
/docs/README.md
该文件就是你项目生成后打开的第一个页面。
-
在
package.json
中添加一些 scripts{ "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" } }
这一步骤是可选的,但我们推荐你完成它。在下文中,我们会默认这些 scripts 已经被添加
-
在本地启动服务器
yarn docs:dev # npm run docs:dev
VuePress
会在 http://localhost:8080 启动一个热重载的开发服务器。- 那么本地的工作你已经完成了,可以看到基本框架已经搭建好了!
部署到xxx.github.io
dev 和 build的个人理解
dev
模式下就会监听文件变化并编译,更改内容在 http://localhost:8080 可以实时看到效果build
模式是发布时使用,将发布生成的文件包上传到github使用,该使用会在后续的自动脚本中用到
package.json配置
目录: /package.json
vuepressBlogDemo
├─── docs
│ ├── README.md
│ └── .vuepress
│ ├── public
│ └── config.js
└── package.json
└── deploy-gh.sh
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs",
"deploy-gh": "deploy-gh.sh"
},
deploy-gh
为自动化脚本,可以理解为你在vuepressBlogDemo
项目文件夹下执行npm run deploy-gh
脚本后,该脚本自动地进入到指定文件夹,并且执行一系列git命令,将你的网页托管到远程仓库。
deploy-gh.sh 配置
新建脚本 /deploy-gh.sh
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run docs:build
# 进入生成的文件夹
cd docs/.vuepress/dist
# 如果是发布到自定义域名
# echo 'www.example' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github:<USERNAME>/<USERNAME>.github.io.git master
# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github:<USERNAME>/<REPO>.git master:gh-pages
# 把上面的 <USERNAME> 换成你自己的 Github 用户名,<REPO> 换成仓库名,比如我这里就是:
git push -f git@github:AssistantLiu/vuepressblog.git master:gh-pages
cd -
config.js 配置
在 docs/.vuepress/config.js
中配置正确的 base
module.exports = {
title: "My Blog",
description: "This is a blog.",
base: '/vuepressblog/'
}
base
不可以随意设置,与github
仓库名保持一致- 例如: 你的仓库名字叫
vuepressblog
- base就是
/vuepressblog/
执行脚本部署
::: warning 注意:
请在项目根目录下运行该命令,否则会找不到deploy-gh文件
:::
yarn deploy-gh # 或者:npm run deploy-gh
- 执行脚本部署的时候,会遇到很多的坑,会发现执行了
npm run deploy-gh
可是我的远程仓库还是空的 - 如果没有推送上去,先检查本地有没有
SSH key
。 - 上述版本是通过ssh的方式推送到
github
,所以要先确保电脑设置了ssh
⛳️ github ssh密钥配置相关内容
功能配置
导航栏链接
在docs/.vuepress/config.js
中配置themmConfig.nav
vuepressblog
├── .gitignore
├── deploy-gh.sh
├── docs
│ ├── .vuepress
│ │ ├── config.js
│ │ ├── dist
│ │ └── public
│ ├── Contact
│ │ └── README.md
│ ├── Home
│ │ ├── README.md
│ │ └── Vuepress
│ ├── README.md
│ ├── Software
│ │ ├── README.md
│ │ └── sublime
│ ├── Study
│ │ ├── Autosar
│ │ └── README.md
│ └── Tutorials
│ ├── README.md
│ └── windows
└── package.json
通过 themeConfig.nav
增加一些导航栏链接:
themeConfig:{
nav:[
{ text: '主页', link: '/' },
{ text: '软件', link: '/Software/' },
{ text: '教程', link: '/Tutorials/' },
{ text: '学习', link: '/Study/' },
{ text: '联系', link: '/Contact/' },
{ text: 'CSDN', link: 'https://blog.csdn/qq_33704787' }
]
}
定制侧边栏配置
如果想为不同的界面配置不同的侧边栏,那么你的目录结构需要遵从以下结构
.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│ ├─ README.md
│ ├─ one.md
│ └─ two.md
└─ bar/
├─ README.md
├─ three.md
└─ four.md
接着,遵循以下的侧边栏配置:
vuepressblog
├── .gitignore
├── deploy-gh.sh
├── docs
│ ├── .vuepress
│ │ ├── config.js
│ │ ├── dist
│ │ └── public
│ ├── Contact
│ │ └── README.md
│ ├── Home
│ │ ├── README.md
│ │ └── Vuepress
│ ├── README.md
│ ├── Software
│ │ ├── README.md
│ │ └── sublime
│ ├── Study
│ │ ├── Autosar
│ │ └── README.md
│ └── Tutorials
│ ├── README.md
│ └── windows
└── package.json
在docs/.vuepress/config.js
中配置themmConfig.sidebar
module.exports = {
themeConfig: {
sidebar: {
'/foo/': [
'', /* /foo/ */
'one', /* /foo/one.html */
'two' /* /foo/two.html */
],
'/bar/': [
'', /* /bar/ */
'three', /* /bar/three.html */
'four' /* /bar/four.html */
],
// fallback
'/': [
'', /* / */
'contact', /* /contact.html */
'about' /* /about.html */
]
}
}
}
最后更新时间
在docs/.vuepress/config.js
中配置themmConfig.lastUpdated
`
module.exports = {
themeConfig: {
lastUpdated: 'Last Updated', // string | boolean
}
}
选项来获取每个文件最后一次 git
提交的 UNIX 时间戳(ms),同时它将以合适的日期格式显示在每一页的底部:
这里要注意的是,只有将文件提交到git后才会显示最后更新时间。
侧边栏显示层级
在docs/.vuepress/config.js
中配置themmConfig.sidebarDepth
`
module.exports = {
themeConfig: {
sidebarDepth: 2 , // 默认 1 提取到 h2,0 为禁用,2 为 h2,h3
displayAllHeaders: false, // 默认值:false 侧边栏只会显示由当前活动页面的标题组成的链接
activeHeaderLinks: true, // 默认值:true 滚动时通过 hash 高亮侧边栏标题
}
}
这里的层级可以理解为md文件的目录层级,会在左边侧边栏显示的标题导航
语言配置
在docs/.vuepress/config.js
中配置locales
`
// 语言配置
locales: {
// 键名是该语言所属的子路径
// 作为特例,默认语言可以使用 '/' 作为其路径。
'/': {
lang: 'zh-CN', // 将会被设置为 <html> 的 lang 属性
}
}
Head标签logo
在docs/.vuepress/config.js
中配置head
module.exports = {
// head 标签中的额外内容
head: [
['link', { rel: 'icon', href: '/images/mail.ico' }] // 这个是标签页 logo
],
}
Git仓库和编辑链接
在docs/.vuepress/config.js
中配置themeConfig.repo
themeConfig.repoLabel
themeConfig.editLinks
module.exports = {
themeConfig: {
repo: 'username/repo', // 你的仓库
repoLabel: 'GitHub', // 导航栏上的文本
editLinks: true,
// 默认为 "Edit this page"
editLinkText: '编辑此页面'
}
}
代码块显示行号
在docs/.vuepress/config.js
中配置markdown
markdown: {
lineNumbers: true // 代码块显示行号
},
首页部署
在docs/README.md
中配置 README.md
vuepressblog
├── .gitignore
├── deploy-gh.sh
├── docs
│ ├── .vuepress
│ │ ├── config.js
│ │ ├── dist
│ │ └── public
│ ├── Contact
│ │ └── README.md
│ ├── Home
│ │ ├── README.md
│ │ └── Vuepress
│ ├── README.md
│ ├── Software
│ │ ├── README.md
│ │ └── sublime
│ ├── Study
│ │ ├── Autosar
│ │ └── README.md
│ └── Tutorials
│ ├── README.md
│ └── windows
└── package.json
::: tip YAML
README.md文件中用到了 🔗 YAML,具体可以去学习如何编写
:::
/docs/README.md
内容:
---
home: true
heroImage: /images/logo.png
heroText: 大蘑菇中文文档
tagline: 学习原来如此简单!
actionText: 开始学习→
actionLink: /Home/
features:
- title: 快速上手
details: 如何快速构建属于自己的Vuepress文档类静态网站
- title: 环境搭建
details: Git、Yarn、NodeJs、Python、C++、utools等
- title: 软件推荐
details: 好用的,好玩的,快速办公,做职场精英
footer: MIT Licensed | Copyright © 2020-present Damogu
---
:book: There is no royal road to learning.
:::tip 提示
this is a tip
:::
:::warning 注意
this is a warning
:::
:::danger 警告
this is a danger
:::
首页必须设置 home 为 true。默认样式与官方文档首页一致。
Makedown相关语法学习
- 工具选择
markdown2
用了几次,非常不喜欢编写界面,行间距太大而且不太友好Typora
多平台的话选择Typota
ulysess
mweb
mac os平台用,收费sublime text
Vscode
能记住的代码的用,专业人士用CSDN
简书
有道云笔记
等都可以选择- csdn关于工具选择
- 简书
- CSDN
- 有道云笔记
- 简书语法教程
Markdown2
- Markdown官网
- win系统上需要安装插件awesomium_v1.6.6_sdk_win.exe,否则会报错
- 如果担心看不懂:简书教程
Email address :Soar360@live
License key :GBPduHjWfJU1mZqcPM3BikjYKF6xKhlKIys3i1MU2eJHqWGImDHzWdD6xhMNLGVpbP2M5SN6bnxn2kSE8qHqNY5QaaRxmO3YSMHxlv2EYpjdwLcPwfeTG7kUdnhKE0vVy4RidP6Y2wZ0q74f47fzsZo45JE2hfQBFi2O9Jldjp1mW8HUpTtLA2a5/sQytXJUQl/QKO0jUQY4pa5CCx20sV1ClOTZtAGngSOJtIOFXK599sBr5aIEFyH0K7H4BoNMiiDMnxt1rD8Vb/ikJdhGMMQr0R4B+L3nWU97eaVPTRKfWGDE8/eAgKzpGwrQQoDh+nzX1xoVQ8NAuH+s4UcSeQ==
Typota
::: tip 快捷键
Ctrl + / 切换到源代码模式
:::
- 懒人首选,傻瓜式操作,安装后即可编辑
- 如果要让工具来选择的话,我更推荐的是Typota软件来编写
makedown
文本 - 推荐搭配QuickTypota插件
跳转
//页内跳转
1. 先定义一个锚(id)
<span id="jump">Hello World</span>
2. 然后使用markdown的语法:
[跳转](#jump)
//链接图片 `vuepress`静态资源存放在`/docs/.vuepress/public`
![权限](/images/权限.gif)
//链接外部网址
[百度](https://www.baidu/)
//链接项目内文件
[工程内文件](/Software/sublime/SublimeText3.md)
emoji大全
:link:
:tada:
自定义容器
::: tip 提示
this is a tip
:::
::: warning 注意
this is a tip
:::
::: danger 警告
this is a tip
:::
Git相关问题
🙍♂some notes about git of liuwanqiang
.gitignore配置
在项目根目录新建文件.gitignore
node_modules/
docs/.vuepress/theme/
docs/.vuepress/dist/
node_modules
为vuepress
依赖包,当项目上传到github肯定要过滤掉让git
忽略node_modules
下的所有文件(npm install操作很方便
)dist
文件是npm run docs:dev
生成的内容,该文件夹是托管在github.io上用来显示页面
github ssh密钥配置
# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github:<USERNAME>/<REPO>.git master:gh-pages
# 把上面的 <USERNAME> 换成你自己的 Github 用户名,<REPO> 换成仓库名,比如我这里就是:
git push -f git@github:AssistantLiu/vuepressblog.git master:gh-pages
- 在配置
deploy-gh.sh
自动脚本的时候有这么一段代码,这里有一个小细节就是,push方式是通过ssh - 所以我们要正确配置ssh,才能将代码提交到仓库
配置ssh
id_rsa
存放在个人电脑上id_rsa.pub
配置在github
上
Github -----ssh
#切换文件夹:
cd ~/.ssh/
#如果没有的话则:
mkdir ../.ssh
#配置信息:
git config --global user.name "Damogu"
git config --global user.email "919740574@qq"
#生成ssh密钥:
ssh-keygen -t rsa -C "919740574@qq"
# 路径选择 : 使用该命令之后, 会出现提示选择ssh-key生成路径, 这里直接点回车默认即可, 生成的ssh-key在默认路径中;
# 密码确认 : 这里我们不使用密码进行登录, 用密码太麻烦;就一路回车下去
#公钥私钥位置:
#例:C:/Users/Han Dong/.ssh 目录
# 1> id_rsa
# 2> id_rsa.pub 公钥(内容加入到github)
#验证是否配置成功:
ssh -T git@github
#<正常情况>
# 然后出现如下信息:
# Warning: Permanently added the RSA host key for IP address '192.30.252.131' to the list of known hosts.
# Hi AssistantLiu! You've successfully authenticated, but GitHub does not provide shell access.
# 验证时可能让你输入YES,当出现以上信息时,说明配置成功,可以连接上GitHub;
#<异常情况>
# ssh: Could not resolve hostname github: \262\273\326\252\265\300\325\342\321\371\265\304\326\367\273\372\241\243
# 出现该问题原因是,因为电脑使用的是代理,公司内网,无法尚未,通过代理另一台电脑实现联网。
版权声明:本文标题:Vuepress建立静态网站 ,从零基础入门到完整建立第一个网页及部署全过程 内容由热心网友自发贡献,该文观点仅代表作者本人, 转载请联系作者并注明出处:https://www.elefans.com/dongtai/1725777746a1041996.html, 本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌抄袭侵权/违法违规的内容,一经查实,本站将立刻删除。
发表评论