VuePress日常使用

peterjxl發表於2024-06-29
Vue

本篇來講解下更多關於 VuePress 的基本用法

‍

配置首頁

現在的頁面太簡單了，我們可以對專案首頁進行配置，修改 docs/README.md （這些配置是什麼後面會說）：

---
home: true
heroImage: https://s3.bmp.ovh/imgs/2022/12/02/bc7428e3916c3a4c.jpg
heroText: Hero標題
tagline: Hero副標題
actionText: 快速上手→
actionLink: /README.md
features:
- title: 簡潔至上
  details: 以Markdown為中心的專案結構，以最少的配置幫助你專注於寫作。
- title: Vue驅動
  details: 享受Vue+ webpack 的開發體驗，在Markdown中使用Vue元件，同時可以使用Vue來開發自定義主題。
- title: 高效能
  details: VuePress為每個頁面預渲染生成靜態的 HTML，同時在頁面被載入的時候，將作為 SPA 執行。
footer: 粵ICP備2022067627號-1  粵公網安備 44011302003646號
---

以上內容使用 yaml 語法，讀者修改的時候注意不要違反了 yaml 語法規則。

‍

重新執行本專案，開啟部落格可以看到如下頁面（已標註各個配置對應的內容）：

​​

‍

‍

‍

熱更新

什麼是熱更新：如果我們已經執行了本專案，在我們修改文件時候，VuePress 能自動更新部落格，不用重新執行也能看到修改後的部落格的內容（相當於會自動編譯執行，不用我們手工編譯執行了）。

VuePress 本身是支援熱更新的，但是有 bug……有時候會熱更新失敗

因此，想要做到熱更新，得修改下命令，新增一個臨時目錄：

"docs:dev": "vuepress dev docs --temp .temp"

‍

由於該臨時目錄只用於解決熱更新失敗的問題，我們在 .gitignore​ 也新增一條忽略的規則：

.temp

‍

注意，我們修改了 package.json 檔案，得重新執行本專案。

在後續的使用過程中，一般文件內容等會自動更新，但如果有修改什麼配置檔案，可能得重啟；

如果還是遇到熱更新失效的話，嘗試重啟看看。

如果你嘗試新增多個文件，建議先停止執行後再重新編譯。

‍

導航欄配置

接下來我們來配置下導航欄。

新建 docs/.vuepress/config.js 配置檔案，檔案內容如下：

module.exports = {
  title: '網站標題',
  description: 'VuePress演示用'
  head: [
    ['link', { rel: 'icon', href: 'https://s3.bmp.ovh/imgs/2023/02/15/16aa54f3ee84602e.webp' }]
  ],
  themeConfig: {
    logo: 'https://s3.bmp.ovh/imgs/2022/12/02/bc7428e3916c3a4c.jpg',
    nav: [
      { text: '首頁', link: '/' },
      { text: '計算機基礎', link: '/CouputerBasic' },
      {
        text: 'Java', items: [
          { text: 'JavaSE', link: '/JavaSE' },
          { text: 'JavaEE', link: 'https://www.peterjxl.com/JavaEE' }
        ]
      },
    ]
  }
}

‍

效果如下：

​​​​​​​​

‍

我們依次介紹下各個配置：

  • title​​：網站的標題，這會決定在瀏覽器標籤頁裡顯示的內容，並且在導航欄也會展示
  • description​：網站的描述，方便 SEO
  • head​​：可配置瀏覽器標籤頁的圖示（icon）
  • themeConfig​：主題的配置，關於主題的內容我們後續會講
  • themeConfig.logo​​：導航欄的 logo。一般來說，部落格的標籤頁的圖示和導航欄的圖示是一樣的
  • themeConfig.nav​​：導航欄的配置，其中 text 就是連結的文字，link 就是連結的地址，並且支援下拉框（當滑鼠懸浮在文字上時出現）。關於連結地址，支援相對路徑（當前域名 + 連結地址）和絕對路徑，並且支援跳轉到第三方網站等。

‍

增加幾篇部落格

當前網站的內容還比較少，不能很好的展示 VuePress 的功能，因此我們來新增幾篇部落格吧！部落格的內容可以簡單寫寫。

我們的部落格都是寫在 docs 資料夾下的，我們新增兩個目錄：Basic 目錄用於存放計算機基礎的部落格，Java 目錄由於存放 Java 相關的部落格，這樣便於分類

我這裡直接建立好，此時專案目錄結構如下：

vuepress-learn
├── docs
│   ├── .vuepress
│   │   └── config.js
│   ├── Basic
│   │   ├── Basic1.md
│   │   └── Basic2.md
│   ├── Java
│   │   ├── JavaEE.md
│   │   └── JavaSE.md
│   └── README.md
├── package-lock.json
└── package.json

此時，對應文章的訪問路徑是這樣的：網址 + 資料夾名字 + 檔名，例如：

  • http://localhost:8080/Basic/Basic1.html
  • http://localhost:8080/Basic/Basic2.html
  • http://localhost:8080/Java/JavaSE.html
  • http://localhost:8080/Java/JavaEE.html

如果直接訪問網址 + 資料夾名字（例如 http://localhost:8080/Java），則預設訪問資料夾下的 README.md

‍

‍

關於文章的內容：預設情況下，如果文件裡有一級標題，則會用一級標題當作標籤頁的 Title：

# Basic1

這裡是計算機基礎第一課！

​

‍

‍

也可用 yaml 語法來配置標題：

---
title: JavaEE
---

‍

‍

配置側邊欄

什麼是側邊欄？簡單來說就是讀文章的時候，左側的導航欄：

​​

‍

‍

我們還是在 config.js 裡配置themeConfig.sidebar​：

module.exports = {
  title: '網站標題',
  head: [
    ['link', { rel: 'icon', href: 'https://s3.bmp.ovh/imgs/2023/02/16/8d42caf2b4ba3334.png' }]
  ],
  themeConfig: {
    logo: 'https://s3.bmp.ovh/imgs/2022/12/02/bc7428e3916c3a4c.jpg',
    nav: [
      { text: '首頁', link: '/' },
      { text: '計算機基礎', link: '/CouputerBasic' },
      {
        text: 'Java', items: [
          { text: 'JavaSE', link: '/JavaSE' },
          { text: 'JavaEE', link: 'https://www.peterjxl.com/JavaEE' }
        ]
      },
    ],

    sidebar: [
      {
        title: 'Basic',
        path: '/Basic/',
        collapsable: false,    //不折疊
        sidebarDepth: 2,
        children: [
          '/Basic/Basic1',
          '/Basic/Basic2'
        ]
      },

      {
        title: 'Java',
        path: '/Java/',
        collapsable: false,
        sidebarDepth: 2,
        children: [
          '/Java/JavaSE',
          '/Java/JavaEE'
        ]
      }
    ]
  }
}

‍

配置後的效果：

​​

‍

注意：側邊欄預設會讀取 Markdown 文件裡配置的標題，如果沒有則會展示文件的訪問路徑（如上圖，不美觀）。

‍

‍

靜態資源

有時候，一些圖片是經常被用到的，我們可以將其放到一個公共資料夾裡，這樣就可以在不同的部落格裡都引用到了。

我們在 .vuepress 目錄下新建 public 目錄，然後放一個圖片，例如 amiliya.jpg。此時資料夾目錄結構如下：

vuepress-learn
├── .temp
├── docs
│   ├── .vuepress
│   │   ├── public
│   │   │   └── amiliya.jpg
│   │   └── config.js
│   ├── Basic
│   │   ├── Basic1.md
│   │   └── Basic2.md
│   ├── Java
│   │   ├── JavaEE.md
│   │   └── JavaSE.md
│   └── README.md
├── package-lock.json
└── package.json

‍

然後我們就可以在部落格或配置檔案裡引用了。例如在 Basic1.md 裡引用：

# Basic1

![](/amiliya.jpg)

這裡是計算機基礎第一課！

‍

效果：

​

‍

又或者在配置檔案裡訪問圖片：

module.exports = {
  themeConfig: {
    logo: '/re0.jpg',
  }
}

更多關於靜態資源的說明，可參考官方文件：靜態資源 | VuePress

‍

如果遇到了困難

如果有遇到什麼問題，除了在命令列裡觀察報錯資訊外，也可以在瀏覽器控制檯裡看有無報錯資訊

遇見了問題首先嚐試自己解決他，利用你的翻譯軟體和搜尋軟體，找到問題的關鍵，處理它。實在不行就找人解決，例如在部落格平臺上提問或者諮詢朋友等等。

‍

獲取原始碼

為了寫本系列的部落格，博主特地新建了一個專案用於演示，相關程式碼已放到 Gitee 和 GitHub 上。

並且，不同功能建立了不同分支，想要獲取本篇文章演示的原始碼只需切換分支即可！

例如，你想執行本篇文章所建立的部落格，可以這樣做：

  1. 開啟命令列
  2. 拉取程式碼：git clone git@gitee.com:peterjxl/vuepress-learn.git​ （也可拉取 GitHub 的）
  3. 跳轉目錄：cd vuepress-learn​
  4. 切換分支：git switch -c VuePressDemo2Basic origin/VuePressDemo2Basic​
  5. 安裝依賴：npm i​
  6. 執行部落格：npm run docs:dev​

‍

參考

  • 官網文件：快速上手 | VuePress，目錄結構 | VuePress，靜態資源 | VuePress
  • GET 新技能！自己的網站突然就不香了

‍

相關文章