Vuepress 博客搭建与 GitHub 静态页面部署

语言: CN / TW / HK

前言

  最近整理博客文章时,偶然想要把本地文章推送到GitHub上维护,毕竟看着很多次的Git提交记录和历史线,时间长了总会萌生再去提交几次的想法。

  但是推送到GitHub后,想要便捷跳转到某篇文章,发现没有一个导航系统可以很好地链接到每篇文章,于是动手搭建一个依赖于Vuepress的博客,为了便于访问,再将其部署为GitHub的静态页面。

  而此篇文章仅是记录Vuepress搭建博客的具体步骤,且仅对内部涉及到的api作解释,更为详细的部分可参考 Vuepress 官方文档。

在线预览

  Don_GW

初始化

  创建项目文件夹blog,接着在文件夹内进行npm初始化。

javascript npm init

  可以先一路回车,后面在编辑器上细致修改各个属性值,况且命令行内也不太方便输入。

  局部安装Vuepress,全局安装一般不推荐,项目还是维护自身的package更好。

javascript npm install -D vuepress

  package.json中添加scripts命令。

javascript { ... "scripts": { "dev": "vuepress dev docs", "build": "vuepress build docs" } }

  创建docs文件夹,并接着创建README.md文档,填入部分内容。

```javascript

Hello VuePress

```

  此时文件夹结构如下。

javascript ├── docs │ ├── README.md ├── node_modules ├── package.json

  运行npm run dev命令,浏览器访问链接可查看到README.md

在这里插入图片描述

页面

  来看一个较为齐全的目录结构。

javascript ├── docs │ ├── .vuepress │ │ ├── public │ │ │ ├── hearder.png │ │ │ ├── logo.png │ │ │ ├── ... │ │ ├── config.js │ ├── pages │ │ ├── article.md │ │ ├── note.md │ │ ├── about.md │ │ ├── ... │ ├── README.md ├── node_modules ├── package.json ├── deploy.sh ├── .gitignore

  各目录或文件释义如下。

  • docs/.vuepress:用于存放vuepress全局的配置、组件、静态资源等
  • docs/.vuepress/public:静态资源目录
  • docs/.vuepress/config.jsvuepress配置文件入口,可配置顶部导航栏和侧边栏等
  • docs/pages:用于存放各个页面
  • docs/pages/README.md:项目首页
  • node_modules:项目依赖
  • package.json:项目描述文件
  • deploy.sh:静态页面发布脚本文件
  • .gitignoregit忽略项配置文件

首页 / 热更新

  README.md粘贴如下内容。

```javascript

home: true heroImage: /header.png heroText: 标题 tagline: 副标题 features: - title: 简洁至上 details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。 - title: Vue驱动 details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。 - title: 高性能 details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。 footer: Copyright © xxx


```

  其中home: true表示将此md作为网站主页。

  heroImage为首页标题图片,位于标题heroText上,且水平居中并以图片原始大小显示,注意heroImage图片的基础路径为docs/.vuepress/public,因此/header.png将引入public文件夹下header.png图片。

  另外tagline为副标题,但是一般作为博客的签名,可以是一句话、一句诗词等。

  footer为首页底部,用作博客声明。

在这里插入图片描述

  但是README.md中粘贴内容后,浏览器刷新并没有任何内容,而命令行则提示重载README.md,即重新运行npm run dev

在这里插入图片描述

  运行后浏览器可查看修改的结果,但是你会发现修改一下README.md就要重新启动一下项目,非常麻烦。

  原因在于md---...---块的部分是页面相关的配置,而修改配置vuepress是不会热更新的(类比vuecli3修改vue.config.js),仅修改页面内容才会热更新。

  解决办法也很简单,修改package.jsondev命令。

javascript { "scripts": { "dev": "vuepress dev docs --temp .temp", ... } }

  运行后会在根目录下生成.temp临时文件。

在这里插入图片描述

  因此若要推送到远程仓库,.gitignore应当忽略掉此目录。

javascript node_modules .temp

导航栏 / 侧边栏

  docs/.vuepress/config.js配置文件内粘贴如下内容。

javascript module.exports = { title: "标题", description: "描述", head: [ [ "link", { rel: "icon", href: "/logo.png" } ] ], themeConfig: { logo: "/logo.png", lastUpdated: "最后更新时间", sidebar: "auto", nav: [ { text: "首页", link: "/" }, { text: "分类", items: [ { text: "文章", link: "/pages/article.md" }, { text: "笔记", link: "/pages/note.md" } ] }, { text: "关于", link: "/pages/about.md" }, { text: "百度", link: "https://www.baidu.com/" } ] } }

  各个属性释义如下。

  • title:网站的标题,并且将会被作为所有页面标题的后缀,默认主题下会显示在导航栏(navbar)上

在这里插入图片描述

  • description:网站的描述,将会以<meta>标签渲染到所有页面

在这里插入图片描述

  • head:网站的icon,其中href的基础路径也是docs/.vuepress/public

在这里插入图片描述

  • themeConfig.logo:导航栏(navbar)前的图标
  • themeConfig.lastUpdated:获取每个md最后一次提交的时间,以合适的格式显示在每个页面的底部

在这里插入图片描述

注意lastUpdated是依赖于git仓库的,因此所在的项目须初始化为git仓库,并且存在一次最新的提交记录

  • themeConfig.sidebarauto表示根据当前页面的标题,自动生成侧边栏。若部分页面不用显示侧边栏,可在页面md内单独配置

```javascript

sidebar: false

```

  • nav:导航栏链接,大致包括下拉分组、链接当前网站页面、链接外部页面等,其中链接当前网站页面时,link基础路径为docs,更为详细说明可参考 官方文档

在这里插入图片描述

发布部署

  按照上述步骤,最后剩下的仅仅是每篇文章的完善,以下开始叙述打包发布的操作流程。

准备工作

  项目根目录创建deploy.sh脚本文件,粘贴如下内容。

```javascript

!/usr/bin/env sh

确保脚本抛出遇到的错误

set -e

生成静态文件

npm run build

进入生成的文件夹

cd docs/.vuepress/dist

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

如果发布到 https://.github.io

git push -f [email protected]:/.github.io.git master

cd - ```

  脚本文件运行的大致过程为,首先执行npm run build打包项目文件,打包后文件位于docs/.vuepress/dist目录,因此执行cd docs/.vuepress/dist进入到目录下。

  然后目录下运行git init初始化为git仓库,暂存目录下所有文件,并做一次提交。其中message为此次提交的说明,可自主修改。

  最后再执行git push -f ... master推送至远程仓库,其中-f表示强制推送,并且使用SSH传输协议,将本地master分支推送到远端。

SSH 公钥

  由于此次传输协议为SSH方式,势必远程仓库要绑定本地的SSH公钥才能推送,因此介绍下本地创建SSH key

  打开Git Bash命令行界面,安装了git的系统,直接鼠标右键选择打开即可。

在这里插入图片描述

  查看本地有无.ssh文件夹,若输出bash: .../.ssh: No such file or directory即表示本地未创建过SSH key

javascript cd ~/.ssh

  创建公钥,其中username为个人邮箱地址,一路回车使用默认值即可。

javascript ssh-keygen -t rsa -C "[email protected]"

  查看公钥。

javascript cat ~/.ssh/id_rsa.pub ssh-rsa ...

  github上选择Settings,侧边栏点击SSH and GPG keys,然后点击New SSH key新增公钥。其中Title为公钥标签,主要帮助你区分公钥的,可以不填。Key即为刚才的公钥,复制粘贴后点击Add SSH key新增公钥。

在这里插入图片描述

创建仓库 / 脚本推送

  github上选择New respository,输入Repository name仓库名,点击Create repository创建仓库。

在这里插入图片描述

注意仓库名称必须为username(你的用户名)+ .github.io的方式,否则需要单独配置

  再次修改下deploy.shusername也是你的用户名。

```javascript

如果发布到 https://.github.io

git push -f [email protected]:username/uaername.github.io.git master ```

  Git Bash命令行运行npm run deploy,注意只能在Git Bash运行,否则会发生错误。

在这里插入图片描述

  若本地没有known_hosts文件,将会收到如下提示,输入yes回车即可。

在这里插入图片描述

  最后收到如下信息即表示推送成功并部署在远端了,并且浏览器访问https//username.github.io将跳转到Vuepress创建的静态博客首页 。

在这里插入图片描述