Migrating to a New Blog

Why Rebuild?

As mentioned before, my previous blog was built with Pelican, primarily using Python Jinja2 syntax as templates to generate content. The advantage of this approach was leveraging Python’s powerful features, but the downside was also clear: it required reinventing many wheels, and writing CSS was quite time-consuming. Therefore, I decided to switch to Vuepress 2 + TypeScript + Tailwind CSS as the new blog framework.

Using Vuepress Theme Hope

The Hope theme is built on Vuepress 2 and comes with a large number of handy components. It also provides a nice blog site style. Compared to some other themes, its development and update activity are relatively high, so I chose this theme as a starting point.

Creating the Project

I’m not a professional front-end developer, so I’ve always been a bit fuzzy about Node.js package managers. I use the default npm to manage dependencies. You can also use pnpm officially recommended officially recommended or yarn for installation.

1
npm init vuepress-theme-hope [dir]

1
pnpm create vuepress-theme-hope [dir]

1
yarn create vuepress-theme-hope [dir]

Starting the Development Server

After following the command-line interactive prompts to set up the site name, author, open-source license, etc., the project will be created. You can see the package.json file in the directory contains some preset commands:

1
"scripts": {
2
  // Build the project
3
  "docs:build": "vuepress build src",
4
  // Clear the cache and start the development server
5
  "docs:clean-dev": "vuepress dev src --clean-cache",
6
  // Start the development server
7
  "docs:dev": "vuepress dev src",
8
  // Upgrade Vuepress and the Hope theme
9
  "docs:update-package": "npx vp-update"
10
},

With this, we can enter the project directory and start the development server.

1
cd [dir]
2
npm run docs:dev

1
cd [dir]
2
pnpm run docs:dev

1
cd [dir]
2
yarn docs:dev

Writing Content

The generated src directory should look something like this:

src/
├── .vuepress
│   ├── config.ts
│   ├── navbar/
│   ├── public/
│   ├── sidebar/
│   ├── styles/
│   └── theme.ts
├── README.md
├── zh/
│   ├── README.md
│   ├── intro.md
│   ├── demo/
│   ├── posts/
│   └── slide.md
├── intro.md
├── demo/
├── posts/
└── slide.md

The /posts/ and /zh/posts/ directories are for storing blog articles. Of course, you can also create other directories or subdirectories to store content of different categories. Articles are written in Markdown format. For supported Markdown syntax, see the theme documentation. In addition to basic syntax support, there are many built-in enhanced features available, which won’t be detailed here.

Default Language

Since I wanted the default site language to be Chinese, the main adjustments needed were for locales and path-related configurations:

1. 1

   File Structure

   Move the contents from /zh/ to the / directory, then delete the /zh/ directory. The corresponding content originally in the root directory was moved in advance to the /en/ directory.

2. 2

   Theme Configuration

   The theme-related configuration file is located at /src/.vuepress/theme.ts. Here you can also configure basic theme information, built-in feature options, plugins, etc.

   The path configurations in locales need to be adjusted.

   1
   export default hopeTheme({
   2
     // ...
   3
     locales: {
   4
       "/": {
   5
         navbar: zhNavbar,
   6
         sidebar: zhSidebar,
   7
         // ...
   8
       },
   9
   
   10
       "/en/": {
   11
         navbar: enNavbar,
   12
         sidebar: enSidebar,
   13
         // ...
   14
       },
   15
     },
   16
     // ...
   17
   });

3. 3

   Site Configuration

   The main site configuration file is located at /src/.vuepress/config.ts, encompassing the site’s basic information, theme configuration, plugin configuration, Markdown configuration, etc.

   Similarly, the path configurations in locales need to be adjusted.

   1
   export default defineUserConfig({
   2
     // ...
   3
     locales: {
   4
       "/": {
   5
         lang: "zh-CN",
   6
         // ...
   7
       },
   8
       "/en/": {
   9
         lang: "en-US",
   10
         // ...
   11
       },
   12
     },
   13
     // ...
   14
   });

4. 4

   Navbar and Sidebar

   Navbar configuration is located at /src/.vuepress/navbar/, and sidebar configuration is at /src/.vuepress/sidebar/. Both contain three files: index.ts, zh.ts, and en.ts, serving as the index, Chinese, and English configurations respectively. We just need to adjust the path configurations in zh.ts and en.ts.

   Taking navbar/en.ts as an example:

   1
   export const enNavbar = navbar([
   2
     "/en/",
   3
     {
   4
       // ...
   5
       prefix: "/en/posts/",
   6
       children: [
   7
         // ...
   8
       ],
   9
     },
   10
   ]);

Custom Components

Writing Components

Thanks to Vuepress’s powerful features, we can use Vue components in Markdown, allowing us to insert custom content into articles. For example, if I wanted to bring back the browser-mimicking decoration container from the old site, I could write a simple Single-File Component (SFC) using Vue. The component path doesn’t have special requirements, but here we follow some conventions and place it in the /src/.vuepress/components/ directory. Create a new file BrowserMockup.vue and fill it with a simple template:

1
<template>
2
  <div>
3
    <slot></slot>
4
  </div>
5
</template>
6

7
<script setup lang="ts"></script>
8

9
<style scoped></style>

Registering Components

At this point, the component is not yet registered in the project. We will use the official plugin @vuepress/plugin-register-components@next to register our custom components for Vuepress:

1
npm install -D @vuepress/plugin-register-components@next

1
pnpm add -D @vuepress/plugin-register-components@next

1
yarn add -D @vuepress/plugin-register-components@next

After installation, we need to register it in /src/.vuepress/config.ts.

1
// ...
2
import { registerComponentsPlugin } from "@vuepress/plugin-register-components";
3
import { getDirname, path } from "vuepress/utils";
4
// ...
5
const __dirname = getDirname(import.meta.url);
6

7
export default defineUserConfig({
8
  // ...
9
  plugins: [
10
    registerComponentsPlugin({
11
      componentsDir: path.resolve(__dirname, "./components"),
12
    }),
13
    // ...
14
  ],
15
  // ...
16
});

After completing the registration, we can use the <BrowserMockup> tag in Markdown to use this component.

1
<BrowserMockup>
2
  <img src="image-path" alt="alternative-text" />
3
</BrowserMockup>

Tailwind Support

Since the Hope theme itself is not developed with Tailwind CSS, we need to configure Tailwind CSS support ourselves. This way, we can conveniently use Tailwind’s utility classes when writing our own components, without struggling to come up with names or worrying about bundle size.

Installing the Tailwind Toolchain

Following the guidance in the Tailwind CSS official documentation, we first need to install some dependencies and initialize the Tailwind CSS configuration file.

1
npm install -D tailwindcss postcss autoprefixer
2
npx tailwindcss init -p

1
pnpm add -D tailwindcss postcss autoprefixer
2
pnpx tailwindcss init -p

1
yarn add -D tailwindcss postcss autoprefixer
2
yarn tailwindcss init -p

Configuring Tailwind

After running the above commands, you should see two files in the project root directory: tailwind.config.cjs and postcss.config.cjs, which are the configuration files for Tailwind CSS and PostCSS, respectively. We need to add some additional configuration to tailwind.config.cjs to facilitate using Tailwind CSS in Vue.

1
/** @type {import('tailwindcss').Config} */
2
module.exports = {
3
  content: [
4
    // Since folders starting with . cannot be matched by wildcards
5
    // we need to manually specify their paths
6
    "./src/.vuepress/**/*.{vue,ts,js,jsx,tsx,md,html}",
7
    "./src/**/*.{vue,ts,js,jsx,tsx,md,html}",
8
  ],
9
  corePlugins: {
10
    // Disable preflight to prevent overriding existing styles
11
    preflight: false,
12
  },
13
  theme: {
14
    extend: {
15
      colors: {
16
        // The following color variables are from the Hope theme
17
        // Add them for use in Tailwind
18
        "theme-color": "var(--theme-color)",
19
        "bg-primary": "var(--bg-color)",
20
        "bg-secondary": "var(--bg-color-secondary)",
21
        "bg-tertiary": "var(--bg-color-tertiary)",
22
        "border-color": "var(--border-color)",
23
        "box-shadow": "var(--box-shadow)",
24
        "text-color": "var(--text-color)",
25
        "card-shadow": "var(--card-shadow)",
26
      },
27
      screens: {
28
        // Adjust some responsive breakpoints based on the Hope theme configuration
29
        sm: "720px",
30
        lg: "960px",
31
        xl: "1440px",
32
      },
33
    },
34
  },
35
  plugins: [],
36
};

To be able to use Tailwind CSS globally, we need to import it in the theme styles. Add the following content to /src/.vuepress/styles/index.scss:

1
@tailwind base;
2
@tailwind components;
3
@tailwind utilities;

Configuring PostCSS

The final step is to ensure Vuepress correctly uses PostCSS during the build process so that Tailwind CSS works properly. We need to add the following content to /src/.vuepress/config.ts:

1
import { defineUserConfig, viteBundler } from "vuepress";
2
import tailwindcss from "tailwindcss";
3
import autoprefixer from "autoprefixer";
4
// ...
5

6
export default defineUserConfig({
7
  // ...
8
  bundler: viteBundler({
9
    viteOptions: {
10
      css: {
11
        postcss: {
12
          plugins: [tailwindcss, autoprefixer],
13
        },
14
      },
15
    },
16
  }),
17
  // ...
18
});

At this point, we can happily use Tailwind CSS in documents, local components, and more.

Deploying to GitHub Pages

The most important step, of course, is making our site accessible to others. Here we choose to use GitHub Pages because it’s free and requires almost no additional configuration.

Preparing the Repository

To deploy the site to the root path of .github.io, we need to create a repository with the same name as the GitHub username can also be all lowercase can also be all lowercase. For example, if the GitHub username is MeteorGuy, then a repository named meteorguy.github.io needs to be created.

For convenience in subsequent operations, it’s best to set the repository to track the remote branch:

1
git remote add origin git@github.com:TeddyHuang-00/teddyhuang-00.github.io.git

Publishing Methods

There are usually several ways to deploy to GitHub Pages. You can:

• Choose the docs folder under the source branch as the site root directory
• Choose the root directory of the source branch as the site root directory
• Choose to use a specific GitHub Actions workflow for deployment

Specific options can be changed in the repository’s Settings -> Pages. Here we use the third method, using GitHub Actions for deployment. This allows for a customizable publishing process with high flexibility.

Configuring GitHub Actions

GitHub Actions is a CI/CD service provided by GitHub that can automatically run scripts in a GitHub repository to achieve functions like automated deployment. Here I kept two deployment methods: one is automatic deployment (automatically building when there is a push update to the main branch), and the other is manual deployment (building locally and then deploying). Both methods have their pros and cons. Automatic deployment is more beginner-friendly, so I recommend using it.

1
# Workflow name
2
name: Deploy Documentation
3

4
# Ensure permissions to access the repository and GitHub Pages
5
permissions:
6
  contents: write
7
  pages: write
8
  id-token: write
9

10
# Trigger condition: only when there is a push to the main branch
11
on:
12
  push:
13
    branches:
14
      # Make sure this is the branch name you are using
15
      - main
16
  # Allows you to manually trigger deployment
17
  workflow_dispatch:
18

19
# Limit concurrency to prevent multiple identical workflows from running simultaneously
20
concurrency:
21
  group: "pages"
22
  cancel-in-progress: true
23

24
jobs:
25
  build-n-deploy:
26
    # Environment required for deployment to GitHub Pages
27
    environment:
28
      name: github-pages
29
      url: ${{ steps.deployment.outputs.page_url }}
30
    runs-on: ubuntu-latest
31
    steps:
32
      - name: Checkout
33
        uses: actions/checkout@v3
34
        with:
35
          fetch-depth: 0
36
          # If your documentation requires Git submodules, uncomment the next line
37
          # submodules: true
38

39
      - name: Setup Node.js
40
        uses: actions/setup-node@v3
41
        with:
42
          node-version: 18
43
          cache: npm
44

45
      - name: Install Dependencies
46
        run: npm ci
47

48
      - name: Build Documentation
49
        env:
50
          NODE_OPTIONS: --max_old_space_size=8192
51
        run: |-
52
          npm run docs:build
53
          > src/.vuepress/dist/.nojekyll
54

55
      # This step is to facilitate our use of a Makefile
56
      # for some post-processing tasks. You can delete this step if not needed.
57
      - name: Make Tasks
58
        run: |
59
          make
60

61
      - name: Setup Pages
62
        uses: actions/configure-pages@v2
63

64
      - name: Upload Files
65
        uses: actions/upload-pages-artifact@v1
66
        with:
67
          path: "src/.vuepress/dist"
68

69
      - name: Deploy to GitHub Pages
70
        id: deployment
71
        uses: actions/deploy-pages@v1

1
.PHONY: post-process
2

3
post-process:
4
  @echo "Hello from Makefile!"

1
# Simple workflow to deploy static content to Pages
2
name: Deploy static content to Pages
3

4
on:
5
  # Triggered when there is a push to the gh-pages branch
6
  push:
7
    branches:
8
      - gh-pages
9

10
  # Allows manual triggering
11
  workflow_dispatch:
12

13
# Permissions to access GITHUB_TOKEN for deploying to GitHub Pages
14
permissions:
15
  contents: read
16
  pages: write
17
  id-token: write
18

19
# Allow only one concurrent workflow at most
20
concurrency:
21
  group: "pages"
22
  cancel-in-progress: true
23

24
jobs:
25
  deploy:
26
    environment:
27
      name: github-pages
28
      url: ${{ steps.deployment.outputs.page_url }}
29
    runs-on: ubuntu-latest
30
    steps:
31
      - name: Checkout
32
        uses: actions/checkout@v3
33
        with:
34
          ref: gh-pages
35
      - name: Setup Pages
36
        uses: actions/configure-pages@v2
37
      - name: Upload Files
38
        uses: actions/upload-pages-artifact@v1
39
        with:
40
          # Upload the entire directory
41
          path: "."
42
      - name: Deploy to GitHub Pages
43
        id: deployment
44
        uses: actions/deploy-pages@v1

1
.PHONY: github clean build
2

3
github: clean build
4
  @echo "======================================================"
5
  @echo "deploying to github"
6
  cd src/.vuepress/dist && \
7
  git init && \
8
  git add -A && \
9
  git commit -m 'deploy at $(shell date)' && \
10
  git branch -m local-build && \
11
  git push -f git@github.com:TeddyHuang-00/teddyhuang-00.github.io.git local-build:gh-pages
12

13
clean:
14
  @echo "======================================================"
15
  @echo "cleaning up output directory"
16
  - rm -rf src/.vuepress/dist
17

18
build:
19
  @echo "======================================================"
20
  @echo "building site"
21
  npm run docs:build

1
make github
2
# or
3
make

Conclusion

At this point, we have completed the setup of a personal blog based on Vuepress. Some parts indeed took me a lot of time, but overall, given the theme features and ecosystem support gained, it’s worth it.

If you found this article helpful, feel free to give it a thumbs up or leave your thoughts in the comments. Have a pleasant day!