用 VuePress 製作說明文件頁面 – 1:安裝

用 VuePress 製作說明文件頁面 - 1:安裝
用 VuePress 製作說明文件頁面 - 1:安裝

本篇要解決的問題

之前常常會需要寫一些 components 的說明文件,給前端同事看或是當作一個如何使用 API 之類的記錄。因為都是比較零星的,所以是用 GitLab 的程式碼功能去存。

但零星的程式碼一多,即便 GitLab 程式碼可以條列出來,還是覺得一眼看過去很花,看不到想找的東西。

之前忘了在哪看到 VuePress 這套開箱即用的靜態網站生成器,想說平常都在用 Vue 了,那不如就用用看這套,看能不能把所有要用的 components 及範例都整理成一個有模有樣的頁面,順便嚇嚇後端 XD~

用了一下後,如果要求的只是一個單純的靜態站,不用做什麼額外設定,裝完後就能用了,如果要加上一些功能,比如客製樣式、裝外掛,那官方文件上也都寫得蠻清楚的。

本系列是整理這幾天在用的時候,有用到的一些功能,更深入的使用就看以後有沒有機會碰到,畢竟目前已解決了所遇到的問題。

本篇主要參考 VuePress 說明文件:https://vuepress.vuejs.org/zh/


安裝前必備

首先,本機必須要安裝好 Node.js,版本在 8.6 以上,還沒裝的朋友可以直接從官網下載安裝。

另外,文件裡面建議是用 Yarn 來裝需要的 Package,所以 Yarn 也安裝一下,在安裝完 Node.js 後,開啟終端機,輸入:

npm install -g yarn

按下 Enter 就會執行安裝。

嗯……用 npm 來裝 Yarn,怎麼覺得有點像拿 IE 裝 Chrome 一樣 XD。

安裝 VuePress

Node.js、Yarn 都安裝完成,先建立一個準備放 VuePress 的資料夾,然後用終端機開啟,首先我們要生成一個 package.json,主要是可以看到我們安裝了哪些 Package,輸入:

yarn init 或 yarn init -y

有沒有「-y」的差別就是會不會詢問我們一些基本問題,如果懶得回答就多打個 -y。

按下 Enter 後,資料夾就會多出一個 package.json 的檔案。

接著要來安裝 VuePress,在終端機輸入:

yarn add -D vuepress

按下 Enter 便會執行安裝,安裝完後目前資料夾會看到這樣:

安裝完 VuePress
安裝完 VuePress

要開啟 VuePress,可以在終端機上輸入:

vuepress dev .

但我們不太想花間去記一些太長的東西 XD,可以有更簡單的方式。

打開 package.json 的檔案,插入以下:

"scripts": {
  "serve": "vuepress dev .",
  "build": "vuepress build ."
}

package.json 的檔案最後會像這樣:

package.json 加入 script
package.json 加入 script

這樣我們只需要在終端機上輸入:

yarn serve

就會開啟我們的 VuePress。

輸入:

yarn build

就會將我們的 VuePress 打包成靜態檔,讓我們放到主機上。

建立首頁

在執行 yarn serve 之前,因為我們目前一個檔案都沒有,開啟了也什麼都看不到。我們先在資料夾的根目錄下新增一個「README.md」檔,在檔案裡面寫上:

# Hello World
新增 README.md
新增 README.md

存檔完後執行 yarn serve,終端機最後會顯示一行:

success [10:48:56] Build 7270a8 finished in 132 ms! ( http://localhost:8081/ )

那個「http://localhost:8081/」就是我們的 VuePress 在開發模式下的網址,打開瀏覽器後貼上網址,就會看見我們的第一個 VuePress 啦~

VuePress 安裝完成
VuePress 安裝完成

注意事項

本篇最後列出一下注意事項:

  1. VuePress 下所有文件都是用 Markdown 寫成,因此檔名要命成 XXXX.md。
  2. 檔名為 README.md 的就會當成首頁。

第 1 點,Markdown 不難,可以參考〈Markdown常用語法筆記〉這篇,或是用一些線上的生成器,如 HackMD

第 2 點,就像我們剛剛在根目錄下創了一個 README.md 檔,就被當作整站的首頁一樣,如果在各個資料夾內建了 README.md 檔,就會當作是那個目錄下的首頁。


原始碼、Demo

本篇開始,原始碼跟 Demo 都會放在 GitHub 上,歡迎取用。

Demo 會隨著系列文更新,所以看到的程式碼會逐漸豐富。

取用之前可以先對本篇點個讚或分享~

原始碼:https://github.com/letswritetw/letswrite-vuepress-document

Demo:https://letswritetw.github.io/letswrite-vuepress-document/


用 VuePress 製作說明文件頁面系列

  1. 安裝
  2. config.js 基本設定
  3. 導覽列
  4. 佈景主題、外掛
  5. 改樣式、加元件
  6. 部署
Summary
用 VuePress 製作說明文件頁面 - 1:安裝
Article Name
用 VuePress 製作說明文件頁面 - 1:安裝
Description
本篇大綱:本篇要解決的問題。安裝前必備。安裝 VuePress。建立首頁。注意事項。之前忘了在哪看到 VuePress 這套開箱即用的靜態網站生成器,想說平常都在用 Vue 了,那不如就用用看這套,看能不能把所有要用的 components 及範例都整理成一個有模有樣的頁面。
Augustus
Let's Write
Let's Write
https://letswrite.tw/wp-content/uploads/2020/08/logo_512.jpg
訂閱
通知
guest

0 Comments
Inline Feedbacks
看所有留言