关于javascript:一篇带你用-VuePress-Github-Pages-搭建博客

前言

最近实现了 TypeScript 最新官网文档 Hanbook 的翻译，一共十四篇，堪称国内的最好 TypeScript4 入门教程之一。为了不便大家浏览，我用 VuePress + Github Pages 搭建了博客，博客成果如下：

博客地址如下：

• Github https://mqyqingfeng.github.io/learn-typescript/
• Gitee http://mqyqingfeng.gitee.io/learn-typescript/

0. VuePress

VuePress 天然不必多说，基于 Vue 的动态网站生成器，格调简洁，配置也比较简单。之所以不应用 VitePress，是因为想应用现有的主题，而 VitePress 不兼容以后 VuePress 的生态系统，至于为什么不抉择 VuePress@next，思考到还处于 Beta 阶段，等稳固后再开始迁徙。

1. 本地搭建

疾速开始同 VuePress 官网：

1. 创立并进入一个新目录

// 文件名自定义
mkdir vuepress-starter && cd vuepress-starter

2. 应用你喜爱的包管理器进行初始化

yarn init # npm init

3. 将 VuePress 装置为本地依赖

yarn add -D vuepress # npm install -D vuepress

4. 创立你的第一篇文档，VuePress 会以 docs 为文档根目录，所以这个 README.md 相当于主页：

mkdir docs && echo '# Hello VuePress' > docs/README.md

5. 在 package.json 中增加一些 scripts

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

6. 在本地启动服务器

yarn docs:dev # npm run docs:dev

VuePress 会在 http://localhost:8080 (opens new window) 启动一个热重载的开发服务器。

2. 根底配置

在文档目录下创立一个 .vuepress 目录，所有 VuePress 相干的文件都会被放在这里。此时你的我的项目构造可能是这样：

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

在 .vuepress 文件夹下增加 config.js，配置网站的题目和形容，不便 SEO：

module.exports = {
  title: 'TypeScript4 文档',
  description: 'TypeScript4 最新官网文档翻译'
}

此时界面相似于：

3. 增加导航栏

咱们当初在页首的右上角增加导航栏，批改 config.js:

module.exports = {
    title: '...',
    description: '...',
    themeConfig: {
        nav: [{ text: '首页', link: '/'},
            { 
                text: '冴羽的 JavaScript 博客', 
                items: [{ text: 'Github', link: 'https://github.com/mqyqingfeng'},
                    {text: '掘金', link: 'https://juejin.cn/user/712139234359182/posts'}
                ]
            }
        ]
    }
}

成果如下：

更多的配置参考 VuePress 导航栏。

4. 增加侧边栏

当初咱们增加一些 md 文档，目前文档的目录如下：

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
|  └─ handbook
|        └─ ConditionalTypes.md
|        └─ Generics.md
└─ package.json

咱们在 config.js 配置如下：

module.exports = {
    themeConfig: {nav: [...],
        sidebar: [
            {
                title: '欢送学习',
                path: '/',
                collapsable: false, // 不折叠
                children: [{ title: "学前必读", path: "/"}
                ]
            },
            {
              title: "根底学习",
              path: '/handbook/ConditionalTypes',
              collapsable: false, // 不折叠
              children: [{ title: "条件类型", path: "/handbook/ConditionalTypes"},
                {title: "泛型", path: "/handbook/Generics"}
              ],
            }
          ]
    }
}

对应的成果如下：

5. 更换主题

当初根本的目录和导航性能曾经实现，但如果我还想要加载 loading、切换动画、模式切换（暗黑模式）、返回顶部、评论等性能呢，为了简化开发成本，咱们能够间接应用主题，这里应用的主题是 vuepress-theme-rec：

当初咱们装置 vuepress-theme-reco：

npm install vuepress-theme-reco --save-dev
# or
yarn add vuepress-theme-reco

而后在 config.js 里援用该主题：

module.exports = {
  // ...
  theme: 'reco'
  // ...
}  

刷新一下页面，咱们会发现一些细节的扭转，比方加载时的 loading 动画、以及反对切换暗黑模式：

6. 增加文章信息

但咱们也会发现，像条件类型这一篇文章， 条件类型（Conditional Types） 居然呈现了两遍，这是因为这个主题主动提取了第一个大题目作为本文的题目，咱们能够在每篇文章的 md 文件中增加一些信息批改：

---
title: 条件类型
author: 冴羽
date: '2021-12-12'
---

此时文章的成果如下：

但如果你不想要题目、作者、工夫这些信息呢，咱们能够在款式里暗藏，这个稍后会讲到。

7. 设置语言

留神，上图的文章工夫，咱们写入的格局为 2021-12-12，然而显示的是 12/12/2021，这是因为 VuePress 默认的 lang 为 en-US，咱们批改一下 config.js：

module.exports = {
  // ...
  locales: {
    '/': {lang: 'zh-CN'}
  },
  // ...
}  

能够发现工夫换了一种展现形式：

8. 开启目录构造

在本来的主题里，咱们发现每篇文章的目录构造呈现在左侧：

而 vuepress-theme-reco 将原有的侧边栏的中的多级题目移出，生成子侧边栏，放在了页面的右侧，如果你要全局开启，可在页面 config.js 里设置开启：

module.exports = {
  //...
  themeConfig: {subSidebar: 'auto'}
  //...
}

此时成果如下：

9. 批改主题色彩

VuePress 基于 Vue，所以主题色用的是 Vue 的绿色，然而 TypeScript 的官网色则是蓝色，那如何批改 VuePress 的主题色呢？

你能够创立一个 .vuepress/styles/palette.styl 文件，文件代码如下：

$accentColor = #3178c6

此时能够发现主题色彩变了：

更多的色彩批改参考 VuePress 的 palette.styl。

10. 自定义批改款式

如果你想自定义批改一些 DOM 元素的款式呢？就比方在暗黑模式下：

咱们发现用作强调的文字色彩比拟黯淡，在暗黑模式下看不清楚，我想改下这个文字的色彩和背景色呢？

而 VuePress 提供了一种增加额定款式的简便办法。你能够创立一个 .vuepress/styles/index.styl 文件。这是一个 Stylus 文件，但你也能够应用失常的 CSS 语法。

咱们在 .vupress 文件夹下创立这个目录，而后创立 index.styl 文件，代码如下：

// 通过查看，查看元素款式申明
.dark .content__default code {background-color: rgba(58,58,92,0.7);
    color: #fff;
}

此时文字就清晰了很多：

那之前咱们提到的暗藏每篇文章的题目、作者、工夫呢，其实也是相似的形式：

.page .page-title {display: none;}

最初的成果如下：

11. 部署

咱们的博客就算是正式的做好了，接下来咱们部署到收费的 Github Pages 上。咱们在 Github 上新建一个仓库，这里我获得仓库名为：learn-typescript。

对应，咱们须要在 config.js 增加一个 base 门路配置：

module.exports = {
      // 路径名为 "/<REPO>/"
    base: '/learn-typescript/',
      //...
}

最终的 config.js 文件内容为：

module.exports = {
    title: 'TypeScript4 文档',
    description: 'TypeScript4 最新官网文档翻译',
    base: '/learn-typescript/',
    theme: 'reco',
    locales: {
        '/': {lang: 'zh-CN'}
    },
    themeConfig: {
        // lastUpdated: '上次更新',
        subSidebar: 'auto',
        nav: [{ text: '首页', link: '/'},
            { 
                text: '冴羽的 JavaScript 博客', 
                items: [{ text: 'Github', link: 'https://github.com/mqyqingfeng'},
                    {text: '掘金', link: 'https://juejin.cn/user/712139234359182/posts'}
                ]
            }
        ],
        sidebar: [
            {
                title: '欢送学习',
                path: '/',
                collapsable: false,
                children: [{ title: "学前必读", path: "/"}
                ]
            },
            {
              title: "根底学习",
              path: '/handbook/ConditionalTypes',
              collapsable: false,
              children: [{ title: "条件类型", path: "/handbook/ConditionalTypes"},
                {title: "泛型", path: "/handbook/Generics"}
              ],
            }
          ]
    }
}

而后咱们在我的项目 vuepress-starter 目录下建设一个脚本文件：deploy.sh，留神批改一下对应的用户名和仓库名：

#!/usr/bin/env sh

# 确保脚本抛出遇到的谬误
set -e

# 生成动态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

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

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

cd -

而后命令行切换到 vuepress-starter 目录下，执行 sh deploy.sh，就会开始构建，而后提交到近程仓库，留神这里提交到了 gh-pages 分支，咱们查看下对应仓库分支的代码：

咱们能够在仓库的 Settings -> Pages 中看到最初的地址：

像我最初生成的地址就是 https://mqyqingfeng.github.io/learn-typescript/

至此，咱们实现了 VuePress 和 Github Pages 的部署。

系列文章

系列文章目录地址：https://github.com/mqyqingfeng/Blog

微信：「mqyqingfeng」，加我进冴羽惟一的读者群。

如果有谬误或者不谨严的中央，请务必给予斧正，非常感激。如果喜爱或者 有所启发，欢送 star，对作者也是一种激励。