VuePress手把手一小時快速踩坑

簡介

官方文檔

快速部署生成靜態網站，便於書寫blog或記錄文件，這個需求始終沒有減少過。因此github上也有許多配套方案，便於建立這類型的靜態網站，例如hexo或Gatsby。透過這個靜態網站排名可以一窺當前stars排名靠前的各種方案。

上週Vue的作者尤大大，提出了一個新的解決方案VuePress。其基本思路借鏡了nuxt.js，但個人認為nuxt更適合中大型應用，這邊不做過多的探討。而VuePress則是更輕量級的應用，考慮到可以在md文件中，嵌入vue語法，因此靈活性相對更強。

核心訴求在解決兩個問題，並更專注於產出內容。

1. SEO優化
2. 頁面加載速度

特性

• 支持在md文件中，嵌入vue的代碼

• 支持PWA

• 集成GA分析

• 默認rwd佈局

• 簡單的UI組件

開始實作一個Demo

新建一個資料夾，並快速初始化

mkdir new_project

npm init -y
复制代码

全域安裝VuePress

npm install -g vuepress
复制代码

創建一個文件資料夾，用來存放md文章

// vuepress官方預設的命名是採用docs，為了避免踩到額外的坑，統一先使用官方文件的格式

mkdir docs
复制代码

配置package.json，添加下述兩行

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
复制代码

創建一個md文件，用來支援首頁呈現，並用於預覽

echo '# Hello VuePress' > docs/README.md
复制代码

啟動本地server端進行預覽

yarn run docs:dev 
or
npm run docs:dev
复制代码

先進行一次打包構建，讓專案資料夾呈現vuepress官方預設的結構

yarn run docs:build
or
npm run docs:build
复制代码

結構

到這邊為止，應該會看到結構呈現如下圖：

其中會看到.vuepress這個資料夾，這是官方預設的命名資料夾。

用於存放組件(components)和設定檔(config.js)。

UI組件

現在看到的本地端server應該只有一個Hello VuePress的簡單頁面，所以需要添加一些組件，來豐富頁面。

引入組件

// cd進入.vuepress資料夾
// 建立一個config.js設定檔
// 準備引入組件

module.exports = {
    
}
复制代码

標題(title)組件

module.exports = {
    title: 'My VuePress'
}

// 將會出現在頁面的左上角，同時也是整個靜態website的標題
复制代码

頂部導覽列nav (自帶簡易搜索功能)

module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'VuePress', link: 'https://vuepress.vuejs.org/' },
    ]
  }
}
复制代码

左側sidebar

sidebar: [
  '/',
  '/about/',
  {
    title: 'Group 1',
    collapsable: false,
    children: [
      '/guide/'
    ]
  }
]

// 除了側邊欄，也可以建立子側邊欄
复制代码

使用Vue組件

除了基本md文件，VuePress也提供在md文件中，嵌入vue文件。

// vuepress預設在.vuepress / components 下的.vue文件，都會自動註冊到全域。

// 故可在任何md文件中自由引用，僅須將components名稱，作為div名稱引入。
复制代码

---

透過下圖來解釋，首先建立一個vue文件，在components資料夾下方。

除了可以使用vue的語法，也能修改樣式。

最後再把寫好的vue文件，引入到想對應的md文件即可

---

部署github pages

在遠端建立一個repository，並clone到本地。 接著到config.js設定檔中添加base

// 在base進行設定後，會自動添加到下面子目錄中所有/開頭的url連結
// 需注意vuepress官方要求路徑名稱後方須添加 '/'

base: '/your repository name/'
复制代码

基本上會長這樣：

base設定完畢，進行打包。

yarn run docs:build
or
npm run docs:build
复制代码

接著把打包好dist內的資料，丟到剛剛clone下來的資料夾，再push上去。

回到遠端repository，進入settings。

拉到下方的GitHub Pages source選擇master分支，theme不用選，再save。 即會自動生成靜態網址，但是網址一開始點進去會是404，需要十幾秒的時間才會部署完成。

項目Demo演示