摘要：故九萬里，則風斯在下矣，而后乃今培風背負青天，而莫之夭閼者，而后乃今將圖南。這里是文件的內容部分最后更新時間最后更新時間默認不開啟，它是基于提交的時間戳，所以我們的靜態站點是需要通過的倉庫進行管理的，并且它是按的時間來計算的。

本blog配套了一個基于 VuePress 的一個簡單的配置案例，此配置案例包含了本blog絕大部分配置案例，更多詳情請移步這里VuePress配置案例

問：這篇文章是干什么的？
答：列舉博客站點常見的配置并提供詳細配置步驟和配置截圖

問：這篇文章適合哪些人？
答：想寫博客，但并不知道如何寫以及知道VuePress但并不知道怎么配置

問：這篇文章目錄怎么理解？
答：看完基礎配置能上手配置，看完進階配置能熟悉了解VuePress

本博客VuePress主版本為0.x，相關配置最新的1.x也兼容，請放心使用。另請確認你的Node.js >= 8

全局安裝(推薦)

通常而言，全局安裝 VuePress 會非常省心，可以通過如下命令進行全局安裝

$ npm install -g vuepress

本地安裝

區別于全局安裝，本地安裝會把npm包安裝在本項目上，生成一個叫node_modules目錄，可以通過如下命令進行本地安裝（需同時安裝vuepress和webpack-dev-middleware）

$ npm install vuepress webpack-dev-middleware --save-dev

基本配置

基本配置下的內容適用于 VuePress 的默認主題，對于自定義主題配置可能會不太一樣

腳本命令

我們需要至少兩個腳本命令，分別用于本地開發和打包上線，腳本命令需要配置在docs/package.json文件中，它的配置如下

{
  "scripts": {
    // 本地開發
    "docs:dev": "vuepress dev docs",
    // 打包上線
    "docs:build": "vuepress build docs"
  }
}

本地開發請使用如下命令，它在本地啟用了一個小型的服務器，你可以在瀏覽器中使用localhost:8080(默認情況下)進行訪問

$ npm run docs:dev

打包命令請使用如下命令，它在.vuepress目錄下生成一個dist文件夾

$ npm run docs:build

項目目錄

VuePress 作為一個靜態網站生成器，它對于項目的目錄是有一定的限制的，一個基本的項目結構如下所示

|-- docs // 特定的目錄
    |-- README.md // 首頁
    |-- .vuepress // 特定的目錄
        |-- config.js // 特定的配置文件
|-- package.json // 腳本命令

首頁

默認主題提供了一個首頁(HomePage)，即上面目錄結構中的README.md文件中的內容，首頁是可選的，對于 VuePress 中默認主題的首頁，我們可以進行如下配置

---
home: true
lang: zh-CN
heroText: A  Personal Blog
heroImage: /logo.jpg
actionText: 開始 →
actionLink: /interview/
features:
- title: A Blog
  details: 專注寫作前端博客，記錄日常所得。
- title: For Me
  details: 故九萬里，則風斯在下矣，而后乃今培風；背負青天，而莫之夭閼者，而后乃今將圖南。
- title: For Interview
  details: 廣州，已入坑?( ′???` )比心
footer: Copyright ? 2019-present Wangtunan
---

以上配置即為本博客的首頁效果

首頁配置說明

在首頁的YAML格式配置中，我們填寫了一些配置，下面我們將詳細描述每一個配置的具體含義

home:true：標記此頁面是否為首頁

lang:zh-CN：表示本頁面的語言為zh-CN(簡體中文)

heroText: 首頁的標題內容

heroImage: 首頁的標題圖片，其中全路徑為docs/.vuepress/public/logo.jpg，默認去public目錄下找靜態資源

actionText: 首頁跳轉按鈕的內容

actionLink: 首頁跳轉按鈕挑戰的路徑，其中全路徑為docs/interview/readme.md，默認readme命名的文件可以省略不寫鏈接的后面內容，省略后的鏈接如上

features: 表明首頁的特征，固定的格式為title + details，以三欄流式布局的方式展示

footer: 為底部內容，與普通的網頁一樣，我們可以在footer里面寫版權信息

導航欄

配置導航欄需要在.vuepress/config.js文件中進行配置

在默認主題下，導航欄需要在themeConfig屬性上進行配置nav，導航欄的兩個重要屬性為text和link，其中text指明了導航的文字內容，link指明了導航的鏈接。

基本導航欄

一個基本的導航欄鏈接可以配置成如下所示

module.exports = {
  // 其它配置
  themeConfig: {
    nav: [
      { text: "首頁", link: "/" },
      { text: "HTML", link: "/html/" },
      { text: "CSS", link: "/CSS/" },
      { text: "JavaScript", link: "/JavaScript/" }
    ]
  }
}

基本導航欄配置結果

導航欄下拉列表

下拉列表需要配置items屬性，它是一個數組，數組里的對象依然是一個普通導航對象，即擁有text和link屬性，一個導航欄下拉列表可以配置成如下所示

module.exports = {
  // 其它配置
  themeConfig: {
    nav: [
      { text: "首頁", link: "/" },
      { text: "前端三劍客", items: [
        { text: "HTML", link: "/html/" },
        { text: "CSS", link: "/CSS/" },
        { text: "JavaScript", link: "/JavaScript/" }
      ]},
      { text: "Vue.jss", link: "/vue/" },
    ]
  }
}

導航欄下拉列表配置結果

禁用導航欄

禁用導航欄分為兩種情況，第一種禁用所有的導航欄，第二種在某個頁面禁用導航欄，針對這兩種不同的情況，相關的配置是不同的，具體如下所示
第一種： 禁用所有導航欄，通過配置navbar屬性為false，此種方式禁用后，將不會存在任何導航欄

module.exports = {
  // 其它配置
  themeConfig: {
    navbar: false
  }
}

第二種： 單個禁用導航欄，在每一個頁面(.md文件)最頂部，配置navbar屬性為false，此種方式禁用后，對應的導航欄依然存在，只是不能點擊跳轉。

---
navbar: false
---

內置搜索

我們在以上配置導航欄的過程中，除了我們配置的導航，還會出現一個搜索框，這就是 VuePress 內置的搜索，內置的搜索只能搜索頁面的h2和h3標題構成的索引，我們依然可以對內置的搜索進行以下配置：

search: 通過配置此屬性為false，來禁用內置搜索

searchMaxSuggestions: 通過配置此屬性為一個數字，對內置的搜索進行最多結果數量的限制

module.exports = {
  // 其它配置
  themeConfig: {
    search: false,
    searchMaxSuggestions: 10
  }
}

側邊欄

側邊欄分組

側邊欄分組即意味著把鏈接進行分組，每一個鏈接對應一個頁面

側邊欄分組可以如下進行配置，其中collapsable屬性設置為false，意味著展開這個分組，屬性設置為true，意味著折疊這個分組。

module.exports = {
  themeConfig: {
    // 其它配置
    sidebar: [
      {
        title: "前端三劍客",
        collapsable: false,
        children: [
          "/CSS/",
          "/HTML/",
          "/JavaScript/"
        ]
      },
      {
        title: "Vue.js",
        collapsable: false,
        children: [
          "/Vue/",
          "/Vue/Vuex.md",
          "/Vue/Vue-Router.md",
        ]
      }
    ]
  }
}

要實現以上分組結果，目錄結構可以如下所示

|-- docs
|   |-- CSS
|   |   |-- README.md
|   |-- HTML
|   |   |-- README.md
|   |-- JavaScript
|   |   |-- README.md
|   |-- Vue
|       |-- README.md
|       |-- Vue-Router.md
|       |-- Vuex.md
|   |-- README.md

側邊欄分組的結果

自動生成側邊欄

如果我們僅僅只是希望能根據.md中的標題自動生成側邊欄的話，可以設置sidebar: auto屬性即可

如果我們要為所有.md都開啟自動生成側邊欄的話，需要進行如下配置

module.exports = {
  themeConfig: {
    // 所有頁面全部開啟自動生成側邊欄
    sidebar: "auto",
  }
}

如果我們只是針對某一個.md文件開啟自動生成側邊欄的話，需要在.md文件的最上方，通過設置YAML屬性，相關配置如下

---
sidebar: auto
---
# Vue.js
這里是Vue.js文件的內容部分

禁用側邊欄

正如上面所提到的多帶帶配置文件的側邊欄，同樣的道理，我們也能多帶帶禁用側邊欄。

---
sidebar: false
---
# Vue.js
這里是Vue.js文件的內容部分

最后更新時間

最后更新時間默認不開啟，它是基于git提交的時間戳，所以我們的靜態站點是需要通過git init的倉庫進行管理的，并且它是按git commit的時間來計算的。

最后更新時間可以通過配置lastUpdated，它的默認值為false，接受字符串(String)和布爾值(boolean)

module.exports = {
  themeConfig: {
    // 1.接受字符串，它設置了最后更新時間的label，例如：最后更新時間：2019年5月3日 21:51:53
    lastUpdated: "最后更新時間",
    // 2.設置true，開啟最后更新時間
    lastUpdated: true,
    // 3.設置false，不開啟最后更新時間(默認)
    lastUpdated: false
}

上一篇/下一篇

如果我們沒有上一篇或者下一篇，只需要把其對應的YAML屬性設置為false即可

上一篇/下一篇可以通過配置YAML的prev和next來顯示的配置，鏈接地址同導航的地址一樣的書寫規則，一個配置了上一篇/下一篇的.md文件可以如下所示

---
prev: /HTML/
next: /JavaScript/
---
# HTML5

這里是HTML5的內容部分

上一篇/下一篇的配置結果如下圖所示

Git倉庫和編輯鏈接

在輸出我們的靜態網站的時候，我們可能需要有一個導航鏈接到我們的GitHub倉庫，對于這個需求我們可以通過如下配置來解決

repo代表我們的鏈接地址，repoLabel代表鏈接的名稱，配置后它會自動出現在我們nav導航的最后一個位置

module.exports = {
  themeConfig: {
    // 其它配置
    repo: "https://github.com/wangtunan/blog",
    repoLabel: "Github",
    nav: [
      { text: "首頁", link: "/" },
      { text: "前端三劍客", items: [
        { text: "HTML", link: "/html/" },
        { text: "CSS", link: "/CSS/" },
        { text: "JavaScript", link: "/JavaScript/" }
      ]},
      { text: "Vue.js", link: "/vue/" },
    ]
  }
}

編輯功能默認是沒有開啟的，我們可以通過配置editLinks來設置是否出現編輯鏈接，editLinkText指明編輯功能的文字內容

一個啟用了編輯鏈接的配置可以如下所示

module.exports = {
  themeConfig: {
    // 其它配置
    repo: "https://github.com/wangtunan/blog",
    repoLabel: "Github",
    editLinks: true,
    editLinkText: "編輯此頁",
    nav: [
      { text: "首頁", link: "/" },
      { text: "前端三劍客", items: [
        { text: "HTML", link: "/html/" },
        { text: "CSS", link: "/CSS/" },
        { text: "JavaScript", link: "/JavaScript/" }
      ]},
      { text: "Vue.jss", link: "/vue/" },
    ]
  }
}

配置了編輯鏈接后結果可能如下圖所示

你也可以通過設置YAML來多帶帶禁止某個.md文件啟用編輯鏈接功能

---
editLink: false
---

Markdown擴展 鏈接

錨鏈接

在VuePress 中所有.md文件中的標題(默認h2和h3)都會自動添加錨點鏈接(anchor)，所以如果我們需要跳轉至固定的錨點，可以如下進行設置

[錨點鏈接](/vuepress/#pwa配置)

內部鏈接

在 VuePress 內部，以.md或者.html結尾的文件，會被轉換成用于SPA導航，它是大小寫敏感的。
如果文件名為README.md，它會被編譯成index.html，所以當我們訪問/vuepress/時，其實就是在訪問/vuepress/README.md或者/vuepress/index.html

自定義容器

VuePress 內置了三種不同狀態的自定義容器，分別有tip、warning和danger三種類型，在緊挨著類型的旁邊，可以設置自定義容器標題，不寫的話默認為TIP，它們的書寫規則如下所示

::: tip 提醒
這里是tip容器
:::

::: warning 警告
這里是警告容器
:::

::: danger 危險
這里是危險容器
:::

三種自定義容器的結果如下圖所示

代碼塊類別

對于不同的代碼塊，需要設置不同的類型進行展示，常見的代碼塊類型有如下所示

html 類型：它表示代碼塊是html格式的

css 類型：它表示代碼塊是css格式的

js 類型：它表示代碼塊是javascript格式的

stylus 類型：它表示代碼塊是stylus格式的，類似的類型還有less和scss

md 類型：它表示代碼塊是markdown格式的

json 類型：它表示代碼塊是json格式的

他們的對應的配置如下所示
HTML格式的代碼塊(觀測代碼塊右上角小角標)

<div class="box">html類型的代碼塊html>

css格式的代碼塊(觀測代碼塊右上角小角標)

.box {
  width: 100px;
  height: 100px;
}

js格式的代碼塊(觀測代碼塊右上角小角標)

console.log("js格式的代碼塊")

其它格式的代碼塊同理，就不在次累述

代碼塊高亮和行號

代碼塊高亮

掘金不支持代碼塊高亮，請自行用VuePress配置查看結果

在Markdown中，我們可以如下所示來進行代碼塊的高亮設置(類型后跟一個花括號)

`` js{4}
export default {
  data () {
    return {
      msg: "Highlighted!"
    }
  }
}
``

它的結果可能會是這樣的(第四行高亮，行數不是從0開始的)

export default {
  data () {
    return {
      msg: "Highlighted!"
    }
  }
}

多行高亮，只需要把行號用逗號隔開即可，例如js {1,3,5}

export default {
  data () {
    return {
      msg: "Highlighted!"
    }
  }
}

代碼塊行號

代碼塊行號配置同樣需要在config.js中進行配置，如下所示

module.exports = {
  // 其它配置
  markdown: {
    // 顯示代碼塊行號
    lineNumbers: true
  }
}

配置后，代碼塊行號的結果如下圖所示

使用Emoji表情

并不是所有Emoji表情都支持(掘金就不支持，無奈只能把例子刪了)

在.md文件中，我們可以使用Emoji表情，你也可以訪問Emoji Search來查詢你喜歡的Emoji表情，訪問Common Emoji來訪問常用的Emoji，一個Emoji可以是這樣寫的

#### 這里是Emoji表情 :tada:
:100: :rocket:

Github風格的表格

有時候我們想要在.md文件中列一些簡單的表格，可以像下面這樣配置

| 序號          | 訂單編號      | 訂單金額|
| -------------|:-------------:| ------:|
| 1             | 20180101     | $1600  |
| 2             | 20180102     |   $12  |
| 3             | 20180103     |    $1  |

以上表格同Github表格風格是一致的，它的結果如下所示

序號	訂單編號	訂單金額
1	20180101	$1600
2	20180102	$12
3	20180103	$1

自動生成目錄

我們有時候希望根據標題自動生成目錄，可以使用[[toc]]來輸出我們的目錄，它默認只列舉h2標題和h3標題

[[toc]]

# H1標題

## h2標題
### h3標題
### h3標題

## h2標題
### h3標題
### h3標題

它的結果可能如下所示

使用Vue模板語法

使用插值

在.md文件中，可以使用 Vue 的插值表達式，像下面這樣

# 插值表達式
1 + 1 的結果是 {{1+1}}

1 + 1 的結果是 {{1+1}}(掘金不支持，自行使用VuePress查看此案例)

指令

除了像上面那樣使用插值表達式，我們還可以使用v-for等指令，下面是一個使用v-for指令的例子

列表渲染的結果是：<span v-for="number in 5">{{number}}span>

列表渲染的結果是：{{number}}(同上，掘金不支持)

使用原生JavaScript和CSS

如果我們要在原生JS中操作DOM，那么一定要記住VuePress的頁面是經過服務端渲染而來，最好是在頁面加載完畢之后再操作DOM

VuePress 賦予了我們在.md文件中直接書寫原生js和css的能力，它們可以是下面這樣的形式

<style>
.box {
  width: 100%;
  height: 100px;
  line-height: 100px;
  text-align: center;
  color: #fff;
  background-color: #58a;
}
style>


#### 使用原生的JS和CSS
<div id="container">div>


<script>
window.onload = function() {
  var dom = document.getElementById("container");
  dom.innerHTML = "box content"
  dom.className = "box"
}
script>

以上代碼的結果如下圖所示

使用CSS預處理器

VuePress 不僅像上面一樣賦予我們使用原生JS和CSS的能力，還賦予我們使用CSS預處理器的能力，它內置了相關CSS預處理器的配置，我們只需要安裝對應的依賴并使用即可，特別要注意的是，VuePress 內置了Stylus，我們無需安裝，可以直接使用，現在讓我們使用Stylus來改寫上面的例子

#### 使用原生的JS和CSS

使用Stylus預處理器后的結果如下圖所示:

使用內置組件

外部鏈接

OutboundLink用來標識一個外部鏈接，它緊跟在鏈接后面，在.md文件中設置外部鏈接時，已默認使用了此組件。

下面是一個外部鏈接的配置，它鏈接到百度

[百度一下](https://www.baidu.com)

此時，百度一下文字后面的小圖標就是內置組件OutboundLink 百度一下(掘金上沒有小圖標)

Badge(角標)

內置組件Badge有三個屬性需要傳遞

text：它指明了角標的內容

type：同自定義容器類似，它有三種不同的類型，分別是tip、warn和error，默認是tip

vertical：它指明了角標同內容的對齊方式，有兩個值，分別是top和middle，默認是top

角標的使用如下所示

#### Vue  
#### Vuex  
#### Vue-Resource

使用Vue組件

VuePress 除了讓我們使用內置組件以外，還可以讓我們使用自己的組件，它默認把在.vuepress/components目錄下所有的組件全局注冊，注冊后我們可以直接在.md文件中使用。 我們先在.vuepress/components目錄下(無則新建)一個customer-component的.vue文件，它的內容如下所示