VuePress 自製獨立頁面,並融入Ant-design UI套件

前言

VuePress 是靜態網站產生器(Static Site Generators, SSGs)的一種,跟hexo是一樣的東西。使用markdown撰寫文章、推上GitHub或GitLab,就會自動將文章渲染成網頁
與hexo主要的差別就是,他是使用Vue.Js來製作的
對於熟悉前端框架的人來說,要再做一些客製化功能就更加容易了!

剛好手上有一需求:

  1. 有不少靜態頁面純圖文資料,內容寫好後基本上不會異動,就算異動,md帶來的內容可維護性相當容易
  2. 要能客製頁面,會做一小工具方便使用。使用前端框架,對於客製頁面達到極大的頁面獨立與可維護性
  3. 小工具是自己用ts開發的library,再打包成js嵌進頁面裡
  4. 頁面無機密性,都是可公開資料(包含小工具)
  5. 無複雜後台需求。使用SSGs可解決長期維護內容的問題 + 快速架站

經多方評估後,覺得使用VuePress最適合了!

唯一缺點大概就是Vue.Js 3 已經幾乎是正式釋出了。VuePress仍是使用2。感覺也沒打算支援3的意思…
不過小工具頁面不算複雜,未來migration也不會是多困難的事
畢竟最重要的功能是包成library。頂多重新再刻頁面

雖然我的需求是類BLOG + 小工具頁面
但對於大部份人來說,blog + 作品集 (尤其前端可以自行刻作品集頁面,也是一種能力展示),也相當適合使用
若是hexo + 喜歡主題改良,再客製作品集的頁面,就相對不容易了

開發過程也踩了不少坑
畢竟 VuePress 相對Hexo冷門不少
網路資源也滿稀缺的QQ

作法

官方文件可參考 VuePress / 在 Markdown 中 使用 Vue
不過說明的有點籠統,需要不少試錯才能建立起來

一、將主題存在本地端

VuePress的主題就不如hexo那樣多樣了
比較紅的主題是vuepress-theme-reco,故以此主題為範例修改
VuePress主題安裝完後,會存在node_modules
在部署時的npm i會覆蓋掉,所以要拷貝一份在本地端
而VuePress啟動流程,會先去抓本地端目錄theme;找不到才會再去node_modules找;再找不到,則使用預設主題

  1. npm i vuepress-theme-reco
  2. node_modules/vuepress-theme-reco,將整個目錄Copy至.vuepress底下
  3. vuepress-theme-reco更名為theme
  4. npm run dev執行開發模式 VuePress blog,執行過程有看到apply local theme,就表示成功了
    wait Extracting site metadata...
    tip Apply local theme at /Users/ryan/Downloads/vuepress-example/.vuepress/theme...
    tip Apply theme local ...
    ...(以下省略)...

二、增加vue檔,放置custom-components目錄

VuePress預設會將放在components底下的vue檔自動註冊成全域組件
但為了避免跟主題現有的東西混在一起,建議自己增加一個目錄分開
若未來有想要跟著主題版更,也比較好把自己的東西轉移至新版

  1. theme底下增加一目錄custom-components (可以取自己喜歡的名字)
  2. 打開config.js,在plugin下,手動註冊此組件
    ['@vuepress/register-components', {
      components: [{
        name: 'MyCustomPage', // 組件名稱依自己需求命名
        path: '@theme/custom-components/MyCustomPage.vue' // 檔名依自己需求命名
      }]
    }]

PS: 不必另外安裝套件@vuepress/register-components,VuePress 框架預設已經內置了

三、增加md檔,用來承載自定頁面

如同撰寫文章那樣,回到根目錄增加一md檔,承載自製vue檔頁面
可以放在任意位置/任意檔名.md
以作品集為例,路徑命名為/portfolio/index.md
因 VuePress 網址會由資料夾 + 檔名來生成,當然也可以在md檔自行指定永久網址
自己知道放在哪裡就可以了!

md檔內容如下:

---
title: 作品集
date: 2020-12-23     <-- 若有需要就加上
categories:          <-- 若有需要就加上
  - 作品集            <-- 若有需要就加上
tags:                <-- 若有需要就加上
  - 作品集            <-- 若有需要就加上
permalink: /portfolio/   <-- 指定永久連結。亦可不指定,直接用`目錄 + 檔名`讓框架自動產生
pageClass: portfolio    <-- 若要客製此頁面的CSS,僅此頁面不要套用全域CSS的話,則增加此參數。CSS參考寫法在下面
---

## 作品集   <-- 仍可如同一般寫文章增加靜態資料
測試內容測試內容測試內容

::: tips
也可以使用reco主題提供框框容器高亮重點文字
:::

<MyCustomPage/>  <-- 承載vue檔,於vue裡撰寫之畫面、功能,將在這裡呈現

若要客製自訂頁面的CSS,至.vuepress/theme/styles/index.styl。增加所需要的CSS
但通常需要動全域的CSS,大概都是寬度、高度問題
雖然是用styl的預處理CSS。也不會太困難

以下提供一範例供參考
CSS最後面的.portfolio則是md檔pageClass後面的名稱。保持一致就可以了

.theme-container.portfolio
    min-width: 700px

到這裡就算是完成了,若有需要融UI套件,則再繼續下一步

四、融入 Ant Design UI 套件

使用框架,除了讓邏輯乾淨之外,最方便的就是可以直接使用現成UI套件了!
這邊的相關資源就少了許多,踩了不少坑才終於試出來…

  1. 安裝套件:npm i ant-design-vue
  2. 打開config.js,在module.exports 根層增加webpack設定
configureWebpack: {
  externals: {
   'ant-design-vue': 'Antd'
  }
},
chainWebpack: (config, isServer) => {
  config.module
    .rule('js') // Find the rule.
    .use('babel-loader') // Find the loader
    .tap(options => Object.assign(options, { // Modifying options
      plugins: [
        ["import", {
          "libraryName": "ant-design-vue",
          "libraryDirectory": "es",
          "style": "css"
        }]
      ]
    }));
  }
  1. 打開enhanceApp.js,註冊需要使用的UI套件

此處比較笨一點就是在自己的vue檔裡也會有重複的import寫法
由於獨立頁面通常不會採用太多UI組件,故我只有引入所需要使用的。也降低整體js大小,避免整包UI打包進去

若有更好的寫法歡迎提供

以下列舉幾個當參考

import { Button, DatePicker, Select, Icon, LocaleProvider, Checkbox } from 'ant-design-vue'; // 此行會在自己的vue檔重覆

export default ({
  Vue,
  siteData,
  isServer
}) => {
  Vue.mixin(postMixin)  // 原本有的
  Vue.mixin(localMixin) // 原本有的
  Vue.use(Button)         // -----以下ant-design UI組件----
  Vue.use(DatePicker)     //   要用多少就引入多少
  Vue.use(Select)  
  Vue.use(Icon)  
  Vue.use(Checkbox)
  Vue.use(Tabs)
  Vue.use(LocaleProvider) // ----以上ant-design UI組件----
  if (!isServer) { // 原本有的
    addLinkToHead('//at.alicdn.com/t/font_1030519_2ciwdtb4x65.css')
    registerCodeThemeCss(siteData.themeConfig.codeTheme)
  }
}

接著就可以開發自己的獨立頁面嘍!

部署至GitLab/GitHub失敗,但本機正常執行?!

安裝core-js。注意要使用2版,3版仍有可能會出錯
npm i core-js@2

參考資料