An article that takes you to build a blog with VuePress + Github Pages

Preface

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

The blog address is as follows:

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

0. VuePress

Naturally, VuePress needless to say, the static website generator based on Vue has simple style and relatively simple configuration. The reason why I don’t use VitePress is because I want to use the existing themes, and VitePress is not compatible with the current VuePress ecosystem. As for why not choose VuePress@next , considering that it is still in the Beta stage, wait until it stabilizes before starting the migration .

1. Build locally

Quick start same as VuePress official website :

1. Create and enter a new directory

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

2. Initialize with your favorite package manager

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 home page:

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

5. Add some scripts in package.json

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

6. Start the server locally

yarn docs:dev # npm run docs:dev

VuePress will start a hot-reloaded development server http://localhost:8080

2. Basic configuration

.vuepress directory under the document directory, and all VuePress related files will be placed here. At this point, your project structure may look like this:

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

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 is now similar to:

3. Add navigation bar

We now add a navigation bar in the upper right corner of the page header, 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, refer to 161bb4d7752b69 VuePress navigation bar .

4. Add a 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

Our config.js is 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 effects are as follows:

5. Change theme

Now the basic directory and navigation functions have been implemented, but if I still want to load loading, switch animation, mode switch (dark mode), return to the top, comment and other functions, in order to simplify the development cost, we can directly use the theme, which is used here The theme is vuepress-theme-rec :

Now we install vuepress-theme-reco:

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

Then quote the topic config.js

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

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

6. Add article information

But we will also find that in an article like Conditional Types, Conditional Types (Conditional Types) actually appeared twice. This is because this topic automatically extracts the first headline as the title of this article. We can write it in each article Add some information modifications to the md file of the article:

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

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

But if you don’t want the title, author, and time information, we can hide it in the style, which will be discussed later.

7. Set the language

Note that for the article time in the picture above, the format we wrote is 2021-12-12 , but 12/12/2021 is displayed. This is because the default lang of en-US is 061bb4d7752d3f. Let's modify config.js:

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

It can be found that the time has changed to a display method:

8. Open the directory structure

In the original theme, we found that the directory structure of each article appeared on the left:

And vuepress-theme-reco removes the multi-level headings in the original sidebar, generates a sub-sidebar, and puts it on the right side of the page. If you want to enable it globally, you can set it to enable it in the page config.js :

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

The effect at this time is as follows:

9. Modify the theme color

VuePress is based on Vue, so the theme color is Vue's green, but the official color of TypeScript is blue. How to modify the theme color of VuePress?

You can create a .vuepress/styles/palette.styl file, the file code is as follows:

$accentColor = #3178c6

At this point, you can find that the theme color has changed:

For more color modification, refer to 161bb4d7752e50 palette.styl 161bb4d7752e51 of .

10. Customize and modify the style

What if you want to customize the style of some DOM elements? For example, in dark mode:

We found that the color of the text used for emphasis is relatively dim and can’t be seen clearly in dark mode. Do I want to change the color and background color of this text?

And VuePress provides an easy way to add additional styles. You can create a .vuepress/styles/index.styl file. This is a Stylus file, but you can also use normal CSS syntax.

We create this directory under the .vupress folder, and then create the index.styl file, the code is as follows:

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

The text is much clearer at this time:

What we mentioned earlier to hide the title, author, and time of each article is actually a similar way:

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

The final effect is as follows:

11. Deployment

Even if our blog is officially finished, we will deploy it to the free Github Pages. Let's create a new warehouse on Github, here I get the warehouse name: learn-typescript .

Correspondingly, we need to add a base path configuration config.js

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

The final config.js file content is:

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

Then we create a script file in the project vuepress-starter deploy.sh , pay attention to modify the corresponding user name and warehouse name:

#!/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 [e-mail]:mqyqingfeng/learn-typescript.git master:gh-pages

cd -

Then switch the command line to the vuepress-starter directory, execute sh deploy.sh , it will start to build, and then submit to the remote warehouse. Note that the gh-pages branch. Let's check the code of the corresponding warehouse branch:

We can see the final address Settings -> Pages in the warehouse:

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

So far, we have completed the deployment of VuePress and Github Pages.

Series of articles

Directory address of series articles: https://github.com/mqyqingfeng/Blog

WeChat: "mqyqingfeng", add me to the only reader group in Kongyu.

If there are mistakes or not rigorous, please correct me, thank you very much. If you like or have some inspiration, star is welcome, which is also an encouragement to the author.