Vuepress建立静态网站 ,从零基础入门到完整建立第一个网页及部署全过程

最新推荐文章于 2024-03-18 09:05:37 发布

CDamogu

最新推荐文章于 2024-03-18 09:05:37 发布

阅读量1.6k

点赞数 1

文章标签： vue.js javascript 前端

本文链接：https://blog.csdn.net/qq_33704787/article/details/125886933

版权

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.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

# 把上面的 <USERNAME> 换成你自己的 Github 用户名，<REPO> 换成仓库名，比如我这里就是：
git push -f git@github.com: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.net/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.com
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.com/)

//链接项目内文件
[工程内文件](/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.com:<USERNAME>/<REPO>.git master:gh-pages

# 把上面的 <USERNAME> 换成你自己的 Github 用户名，<REPO> 换成仓库名，比如我这里就是：
git push -f git@github.com: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.com"


#生成ssh密钥：
ssh-keygen -t rsa -C "919740574@qq.com"
#    路径选择 : 使用该命令之后, 会出现提示选择ssh-key生成路径, 这里直接点回车默认即可, 生成的ssh-key在默认路径中;
#    密码确认 : 这里我们不使用密码进行登录, 用密码太麻烦;就一路回车下去

#公钥私钥位置：
#例：C:/Users/Han Dong/.ssh 目录
#	1> id_rsa
#	2> id_rsa.pub  公钥（内容加入到github）

#验证是否配置成功：
ssh -T git@github.com

#<正常情况>
#	然后出现如下信息：
#	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.com: \262\273\326\252\265\300\325\342\321\371\265\304\326\367\273\372\241\243
#	出现该问题原因是，因为电脑使用的是代理，公司内网，无法尚未，通过代理另一台电脑实现联网。

CDamogu

关注

1
点赞
踩
3

收藏

觉得还不错? 一键收藏
打赏
0
评论
Vuepress建立静态网站 ,从零基础入门到完整建立第一个网页及部署全过程

VuePress是一款使用Vue驱动的静态网站生成器，是Vue的作者EvanYou为了方便文档的编写而开发的。默认主题与Vue官方文档一致简洁，少配置，高性能Markdown专为技术文档提供拓展自带PWA自定义主题，可定制程度完全由自己决定VuePress中文网Vuepress在中配置`{}}选项来获取每个文件最后一次git提交的UNIX时间戳(ms)，同时它将以合适的日期格式显示在每一页的底部tip提示warning注意。...
复制链接

扫一扫