通過vuepress管理專案文件(一)

摘要： 這篇文章主要是記錄自己在使用vuepress過程中所遇到的問題以及如何一步一步的解決問題。 安裝vuepress前，請確保你的 Node.js 版本 >= 8 全域性安裝 # 安裝 yarn global add vuepress # 或者：npm install -g vu...

這篇文章主要是記錄自己在使用vuepress過程中所遇到的問題以及如何一步一步的解決問題。

安裝vuepress前，請確保你的 Node.js 版本 >= 8

全域性安裝

# 安裝
yarn global add vuepress # 或者：npm install -g vuepress

# 新建一個 markdown 檔案
echo '# Hello VuePress!' > README.md

# 開始寫作
vuepress dev .

# 構建靜態檔案
vuepress build .

注意 ：vuepress dev . 和vuepress build . 後面的. 。

在現有專案中安裝

# 將 VuePress 作為一個本地依賴安裝
yarn add -D vuepress # 或者：npm install -D vuepress

# 新建一個 docs 資料夾
mkdir docs

# 新建一個 markdown 檔案
echo '# Hello VuePress!' > docs/README.md

# 開始寫作
npx vuepress dev docs

接著，在package.json 里加一些指令碼:

{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}

開始寫作

yarn docs:dev # 或者：npm run docs:dev

第一個坑：我的專案就是依賴webpack 3.6.0 同時也是用npm安裝依賴，然後繼續使用npm安裝vuepress，然後執行npx vuepress dev docs 的時候報錯了，上網查了好久也沒有解決問題，最後使用yarn安裝vuepress成功了。

如果你的現有專案依賴了 webpack 3.x，推薦使用 yarn而不是 npm 來安裝 VuePress。

要生成靜態的 HTML 檔案，執行：

yarn docs:build # 或者：npm run docs:build

預設情況下，檔案將會被生成在.vuepress/dist ，也可以通過.vuepress/config.js 中的dest 欄位來修改.

以上步驟都成功以後，就可以在瀏覽器總看到頁面了，接下來就是對頁面進行佈局

主題配置

本文是根據vuepress預設主題配置

1.首頁

在docs資料夾下建立.vuepress資料夾 和README.md檔案 。(如果以及有了就不要再新建)

根目錄下的README.md檔案可以當作首頁，在檔案中加入下面文字：

---
home: true
heroImage: /hero.png
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 簡潔至上
details: 以 Markdown 為中心的專案結構，以最少的配置幫助你專注於寫作。
- title: Vue驅動
details: 享受 Vue + webpack 的開發體驗，在 Markdown 中使用 Vue 元件，同時可以使用 Vue 來開發自定義主題。
- title: 高效能
details: VuePress 為每個頁面預渲染生成靜態的 HTML，同時在頁面被載入的時候，將作為 SPA 執行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

可以根據自己的需要新增、刪除、修改，這就完成了首頁的佈局

actionLink/zh/guide/ 就是首頁後要顯示的下一個頁面

接下來在docs資料夾中建立guide資料夾 (根據自己的需要命名)。這個資料夾中放的是markdown 檔案，每一個markdown 檔案對應一個頁面。至於頁面之間的跳轉和頁面導航欄和側邊欄佈局在config.js 檔案中設定。

VuePress 網站必要的配置檔案是.vuepress/config.js ，它應該匯出一個 JavaScript 物件：

module.exports = {
title: 'Hello VuePress',
description: 'Just playing around'
}

對於上述的配置，如果你執行起 dev server，你應該能看到一個頁面，它包含一個頁頭，裡面包含一個標題和一個搜尋框。

2.導航欄

可以通過themeConfig.nav 增加一些導航欄連結:

// .vuepress/config.js
module.exports = {
themeConfig: {
nav: [
{text: '指南',link:'/guide/install/install'}
]
}
}

當你提供了一個items 陣列而不是一個單一的link 時，它將顯示為一個下拉列表 ：

module.exports = {
themeConfig: {
nav: [
{
text: 'Languages',
items: [
{ text: 'Chinese', link: '/language/chinese/' },
{ text: 'Japanese', link: '/language/japanese/' }
]
}
]
}
}

3.側邊欄

想要使側邊欄（Sidebar）生效，需要配置themeConfig.sidebar

// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: [
{
title: '開發指南',
collapsable: false, //是否展開
},
['./guide/install/install','安裝'],
['./guide/started/started','快速上手'],
{
title: '元件',
collapsable: false
},
['./guide/icon/icon','icon'],
['./guide/button/button','button'],
]
}
}

現在頁面基本也搭建完成，可以在頁面之間進行切換。下一步是如何在markdown 中使用vue元件，也就是在頁面中展示自己的專案。

在markdown中使用Vue

在.vuepress 中建立components 資料夾。

所有在.vuepress/components 中找到的*.vue 檔案將會自動地被註冊為全域性的非同步元件。

.
└─ .vuepress
└─ components
├─ demo-1.vue
└─ Foo
└─ demo-2.vue

可以直接使用這些元件在任意的 Markdown 檔案中（元件名是通過檔名取到的）：

<demo-1/>
<Foo-demo-2/> //檔名和元件名之間同`-`連線

完成這一步以後就可以在頁面中看到自己的元件在頁面中展示了，但是在執行下面命令的時候會報錯：

報錯原因參考官網文件## 瀏覽器的 API 訪問限制

yarn docs:build # 或者：npm run docs:build

解決這個問題只需要在markdown 檔案中使用<ClientOnly></ClientOnly> 將元件包裹起來。如：

<ClientOnly>
<Foo-demo-2/>
</ClientOnly>

注意：在markdown檔案中如果需要給元件名縮排，不要用tab 鍵，會被當做markdown 語法解析。

到這一步，基本上可以在頁面中展示自己的元件。下一篇將繼續寫如何通過vue元件實現跟Element 相似的效果。