經過VuePress管理項目文檔(一)

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管理項目文檔(二)

相關連接

完整的Vue組件代碼以及完整的文檔，僅適用於我的參考學習:

文檔預覽地址：預覽連接
使用VuePress編輯文檔的代碼訪問：組件文檔
完整代碼：組件代碼
Vue組件開發