One article to quickly teach you how to build a blog using VuePress + Github Pages (practical)

This article will share with you a VuePress practical experience. Through this article, I will teach you how to quickly build a blog using VuePress Github Pages. I hope it will be helpful to everyone.

Recently completed the translation of Hanbook, the latest official TypeScript document. There are fourteen articles in total. It can be called one of the best TypeScript4 introductory tutorials in China. In order to make it easier for everyone to read, I used VuePress Github Pages to build a blog. The blog effect is as follows:

0. VuePress

VuePress Needless to say, the static website generator based on Vue has a simple style and relatively simple configuration. The reason why I don’t use VitePress is because I want to use an existing theme, and VitePress is not compatible with the current VuePress ecosystem. As for why I don’t choose VuePress@next, considering that it is still in Beta stage, wait until it stabilizes before starting the migration. [Related recommendations: "vue.js Tutorial"]

1. Local build

Quick startSame as VuePress official website:

1. Create and enter a new directory

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

2. Use your favorite package manager to initialize

yarn init # npm init

3. Install VuePress as a local dependency

yarn add -D vuepress # npm install -D vuepress

4 , create your first document, VuePress will use docs as the document root directory, so this README.md is equivalent to the homepage:

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

5. Add some scripts

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

## in package.json #6. Start the server locally

yarn docs:dev # npm run docs:dev

VuePress will start a hot-reloaded development server at

http://localhost:8080 (opens new window).

2. Basic configuration

Create a

.vuepress directory in the document directory, where all VuePress related files will be placed. At this time, your project structure may look like this:

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

Add

config.js under the .vuepress folder to configure the title and description of the website to facilitate SEO:

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

The interface at this time is similar to:

3. Add navigation bar

We now add a navigation bar in the upper right corner of the top of the page , modify

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' }
                ]
            }
        ]
    }
}

The effect is as follows:

For more configuration, please refer to the VuePress navigation bar:

https://vuepress.vuejs.org/zh/theme/default-theme-config.html#Navigation bar

4. Add sidebar

Now we add some md documents. The current document directory is as follows:

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

We configure it in

config.js as follows:

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" }
              ],
            }
          ]
    }
}

The corresponding effect is as follows:

5. Change the theme

Now the basic directory and navigation functions have been implemented, but if I also want to load, switch animations, and mode switch (dark mode), As for functions such as returning to the top and comments, in order to simplify development costs, we can use the theme directly. The theme used here is vuepress-theme-rec (https://vuepress-theme-reco.recoluan.com/):

Now we install vuepress-theme-reco:

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

Then reference the theme in

config.js:

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

Refresh the page and we will find some details Changes, such as loading animation during loading, and support for switching to dark mode:

6. Add article information

But we will also find, like conditions In this article,

Conditional Types actually appears twice. This is because this topic automatically extracts the first headline as the title of this article. We can add it to the md of each article. Add some information modifications to the file:

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

The effect of the article at this time is as follows:

但如果你不想要标题、作者、时间这些信息呢，我们可以在样式里隐藏，这个稍后会讲到。

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: &#39;/learn-typescript/&#39;,
  	//...
}

最终的 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 中看到最后的地址：

Like the last address I generated is https://mqyqingfeng.github.io/learn-typescript/

At this point, we are done Deployment of VuePress and Github Pages.

For more programming-related knowledge, please visit: Introduction to Programming! !

The above is the detailed content of One article to quickly teach you how to build a blog using VuePress + Github Pages (practical). For more information, please follow other related articles on the PHP Chinese website!