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

qfstudy發表於2018-12-03
Vue

這篇文章主要是記錄自己在使用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] 的陣列。 具體配置可以根據官網配置：預設主題配置

這是瀏覽器顯示效果：

1.png

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

在markdown中使用Vue

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

如果需要引入靜態檔案，可以在.vuepress下新建public資料夾，裡面可以放靜態檔案。

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

這是docs資料夾目錄結構

2.png

.
└─ .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語法解析。

瀏覽器效果圖

3.png

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

相關連結

完整的Vue元件程式碼以及完整的文件，僅適用於個人參考學習:

文件預覽地址：預覽連結

使用VuePress編輯文件的程式碼訪問： 元件文件

完整程式碼：元件程式碼

Vue元件開發

相關文章