博客 / 詳情

返回

手摸手教你用VitePress + Github Pages搭建博客

前言

這是一期關於VitePress搭建博客並將它部署到Github Pages的教程文章，起因是把年前給自己立的一個flag實現以及最近打算把之前的學過的知識鞏固一下

因此打算搭建一個博客來作為平時寫作的地方。

我的博客地址如下:https://xuxing409.github.io/my-blog/

VitePress是什麼

在搭建博客之前,我們先做一下準備工作, 瞭解一下VitePress是個什麼東東。VitePress是由Vue + vite支持的靜態站點生成器。我們看到他是由基於Vue框架構建的，因為Vue本身使用起來不難，所以VitePress使用起來也很簡單；並且它還是基於vite的，那麼代表我們可以享受到Vite帶來的開發體驗！VitePress靈感來源於VuePress，現在VuePress2也支持了Vue3和Vite，但是開發團隊由於精力有限決定把重心放到VitePress上，所以我們選擇VitePress來進行博客搭建。

項目搭建

1. 創建目錄

創建一個新目錄，並進入

mkdir my-blog && cd my-blog

2. 初始化package.json

使用包管理工具初始化項目package.json文件，我這裏以npm為例

npm init -y

3. 準備工作

項目安裝VitePress為開發依賴

 pnpm add -D vitepress

如果此時你的項目出現Issues with peer dependencies found這個提示不影響項目運行

如果不想看見它可以在package.json配置如下,作用是忽略對等依賴警告

  "name": "my-blog",
  "version": "1.0.0",
  ...
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": [
        "@algolia/client-search",
        "search-insights"
      ]
    }
  }

4. 添加命令

接着在package.json文件中scripts添加如下命令

  "scripts": {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "preview": "vitepress preview docs"
  }

5. 啓動服務

在本地運行項目vitepress會在http://localhost:5173/啓動一個熱更新的開發服務器

pnpm dev

點開鏈接即可看到如下我們項目當前的樣子,vitepress幫我們默認添加了一個標題與暗黑模式功能

基礎配置

1. 創建配置文件

項目當前只有一個vitepress默認的架子,我們去給他添加一些配置。在項目中創建一個docs目錄,並在其中創建一個.vitepress目錄與config.js文件。

2. 編寫基礎描述

在其中編寫title與description方便SEO。

// docs/.vitepress/config.js
export default {
  // 站點級選項
  title: "是檸新呀的博客", // 網站標題
  description: "是檸新呀用來寫博客的地方", // 網站描述

  themeConfig: {
    // 主題級選項
  },
};

3. 配置導航欄

它是顯示在頁面頂部的位置,可以在themeConfig下nav中配置。這裏link我們僅配置到 / 他會自動匹配到目錄的 index.md 文件,因為index.md是vitepress的默認入口文件,在vuepress中使用的是README.md作為默認的入口文件

export default {
  themeConfig: {
    nav: [
      { text: '關於', link: '/about' },
      {
        text: '大前端',
        items: [
          { text: "html", link: "/bigFrontEnd/html/" },
          { text: "css", link: "/bigFrontEnd/css/" },
          { text: "js", link: "/bigFrontEnd/js/" },
        ]
      }
    ]
  }
}

此時我們的界面會呈現如下:

4. 配置側邊欄

它是顯示在頁面左側的位置。我們配置一個根據頁面路徑的不同顯示不同的側邊欄。

export default {
  themeConfig: {
    sidebar: {
      "/bigFrontEnd/html/": {
        text: "html",
        items: [
          { text: "html", link: "/bigFrontEnd/html/" },
          { text: "html1", link: "/bigFrontEnd/html/html1" },
          { text: "html2", link: "bigFrontEnd/html/html2" },
        ],
      },
      "/bigFrontEnd/css/": {
        text: "css",
        items: [
          { text: "css1", link: "/bigFrontEnd/css/css1" },
          { text: "css2", link: "/bigFrontEnd/css/css2" },
        ],
      },
      "/bigFrontEnd/js/": {
        text: "js",
        items: [
          { text: "js1", link: "/bigFrontEnd/js/js1" },
          { text: "js2", link: "/bigFrontEnd/js/js2" },
        ],
      },
    },
  }
}

5. 創建索引index.md文件

我們在bigFrontEnd目錄下創建html目錄,並在其下面創建index.md、htm1.md、html2.md。編寫index.md文件創建一個目錄索引

# html 專題

## 目錄

- [html1](./html1.md)
- [html2](./html2.md)

這裏我們分別為html、css、js配置了不同的側邊欄,當我們點擊html時側邊欄會如下顯示:

此時我們已經配置完畢側邊欄,並且還創建了一個專題目錄,但是我們看到下方的下一篇仍是顯示的英語Next page,如果想要修改的話我們再在themeConfig中配置一下docFooter就可以了，具體如下

export default {
  themeConfig: {
    docFooter: {
          prev: "上一篇",
          next: "下一篇",
        },
    }
}

6. home主頁配置

目前為止我們已經完成了大部分配置,但是主頁目前還是空白,那麼現在我們開始簡單配置一下主頁, 在docs/index.md中配置layout: home即可使用默認主題提供的首頁佈局,我們使用vitepress文檔的樣式。
如果想要自定義,那麼可以看看官方home具體接口説明https://vitepress.dev/zh/reference/default-theme-home-page

  ---
    layout: home

    hero:
      name: 是檸新呀的博客
      text: awesome-front-end-world.
      tagline: 前端 知識體系地圖
      image:
        src: /logo.jpg
        alt: logo
      actions:
        - theme: brand
          text: Get Started
          link: /bigFrontEnd/html/
        - theme: alt
          text: View on GitHub
          link: https://github.com/vuejs/vitepress
    ---

    <style>
    :root {
      --vp-home-hero-name-color: transparent;
      --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe 30%, #41d1ff);

      --vp-home-hero-image-background-image: linear-gradient(-45deg, #bd34fe 50%, #47caff 50%);
      --vp-home-hero-image-filter: blur(44px);
    }

    @media (min-width: 640px) {
      :root {
        --vp-home-hero-image-filter: blur(56px);
      }
    }

    @media (min-width: 960px) {
      :root {
        --vp-home-hero-image-filter: blur(68px);
      }
    }
    </style>

這裏接口配置的靜態資源請在docs目錄下創建public目錄，並且引入對應的靜態資源文件即可。

7. 網站logo配置

配置完畢後如果沒有顯示可以嘗試強制刷新緩存

// .vitepress/config.js
export default {
  head: [
    // 配置網站的圖標（顯示在瀏覽器的 tab 上）
    ["link", { rel: "icon", href: `/favicon.ico` }],
  ],
}

此時我們的頁面顯示如下

至此可以看到我們已經完成了博客的基本配置，那麼接下來我們將開始學習如何利用Github Pages部署我們的博客

部署Github Pages

1. 創建倉庫

輸入名字後，注意將本項目的base也修改為同名 

// .vitepress/config.js
const base = "/blog-demo/"; // [!code ++]
export default {
  base,  // [!code ++]
  // 站點級選項
  title: "是檸新呀的博客",
  description: "是檸新呀用來寫博客的地方",
  head: [
     ["link", { rel: "icon", href: `/favicon.ico` }], // [!code --]
    // 配置網站的圖標（顯示在瀏覽器的 tab 上）
    ["link", { rel: "icon", href: `${base}favicon.ico` }],  // [!code ++]
  ],
  ...
};

2. 創建.gitignore

根目錄創建.gitignore文件並寫入內容

node_modules
dist
cache
.temp
.DS_Store

3. 上傳代碼到github

根據提示提交代碼到github倉庫，這裏不再贅述

4. 開啓Github Action

根據下圖提示開啓Github Action支持

5. 配置.github/workflows/deploy.yml文件

根目錄新建同名文件夾與文件,文件內容參考如下

name: Deploy Pages

# 觸發條件，push到main分支或者pull request到main分支
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

  # 支持手動在工作流上觸發
  workflow_dispatch:

# 設置時區
env:
  TZ: Asia/Shanghai

# 權限設置
permissions:
  # 允許讀取倉庫內容的權限。
  contents: read
  # 允許寫入 GitHub Pages 的權限。
  pages: write
  # 允許寫入 id-token 的權限。
  id-token: write

# 併發控制配置
concurrency:
  group: pages
  cancel-in-progress: false

# 定義執行任務
jobs:
  # 構建任務
  build:

    runs-on: ubuntu-latest

    # node v20 運行
    strategy:
      matrix:
        node-version: [20]

    steps:
      # 拉取代碼
      - name: Checkout
        uses: actions/checkout@v3
        with:
          # 保留 Git 信息
          fetch-depth: 0

      # 設置使用 Node.js 版本
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      # 使用 最新的 PNPM
      # 你也可以指定為具體的版本
      - uses: pnpm/action-setup@v2
        name: Install pnpm
        with:
          version: latest
          # version: 9
          run_install: false

        # 安裝依賴
      - name: Install dependencies
        run: pnpm install --frozen-lockfile

        # 構建項目
      - name: Build blog project
        run: |
          echo ${{ github.workspace }}
          pnpm build

        # 資源拷貝
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./docs/.vitepress/dist
          destination: ./_site

        # 上傳 _site 的資源，用於後續部署
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  # 部署任務
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

我最後生成的地址就是https://xuxing409.github.io/blog-demo/,以後我們每次推送代碼github就會自動進入流水線構建啦

Github源碼地址: https://github.com/xuxing409/blog-demo

至此,我們已經完成了VitePress的搭建和GitHub Pages的部署了。

github-pages , vitepress , 博客搭建 , 前端
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.