VuePress

這篇文章主要是記錄自己在使用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 actionText: 快速上手 → actionLink: /guide/install/install ---

可以根據自己的需要添加、刪除、修改，這就完成了首頁的布局
actionLink: /guide/install/install就是首頁后要顯示的下一個頁面

接下來在docs文件夾中創建guide文件夾(根據自己的需要命名)。這個文件夾中放的是markdown文件，每一個markdown文件對應一個頁面。至於頁面之間的跳轉和頁面導航欄和側邊欄布局在config.js文件中設置。
VuePress 網站必要的配置文件是 .vuepress/config.js，它應該導出一個 JavaScript 對象：

module.exports = { title: 'VuePress', description: 'VuePress', }

對於上述的配置，運行yarn docs:dev，你應該能看到一個頁面，它包含一個頁頭，里面包含一個標題和一個搜索框。

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'], ] } }

可以省略 .md 拓展名，同時以 / 結尾的路徑將會被視為 */README.md
如果想要顯示地指定鏈接的文字，使用一個格式為 [link, text] 的數組。
具體配置可以根據官網配置：默認主題配置

這是瀏覽器顯示效果：

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

在markdown中使用Vue

在.vuepress中創建components文件夾。
所有在 .vuepress/components 中找到的 *.vue 文件將會自動地被注冊為全局的異步組件。

如果需要引入靜態文件，可以在.vuepress下新建public文件夾，里面可以放靜態文件。

因為本文的案例是展示Icon圖標，所有引入了svg.js，svg.js可以在http://www.iconfont.cn/中獲取，本文使用## symbol引用具體方法請訪問官網。放在public文件夾中，可以在components文件夾中的組件引入。

這是docs文件夾目錄結構

.
└─ .vuepress └─ components ├─ demo-1.vue └─ Icon └─ vi-icon.vue

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

<demo-1/> <Icon-vi-icon/> //文件名和組件名之間同`-`連接

完成這一步以后就可以在頁面中看到自己的組件在頁面中展示了，但是在運行下面命令進行打包的時候會報錯：
報錯原因參考官網文檔：瀏覽器的 API 訪問限制

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

解決這個問題只需要在使用Vue組件的markdown文件中使用<ClientOnly></ClientOnly>將組件包裹起來。如：

<ClientOnly> <Icon-vi-icon/> </ClientOnly>

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

瀏覽器效果圖

到這一步，基本上可以在頁面中展示自己的組件。下一篇將繼續寫如何通過Vue組件實現跟：Element相似的效果。
通過VuePress管理項目文檔(二)