VuePress 手摸手教你搭建一個類Vue文件風格的技術文件/部落格

OBKoro1發表於2018-09-10
Vue

前言：

VuePress是尤大為了支援 Vue 及其子專案的文件需求而寫的一個專案，VuePress介面十分簡潔，並且非常容易上手，一個小時就可以將專案架構搭好。現在已經有很多這種型別的文件，如果你有寫技術文件的專案的需求，VuePress絕對可以成為你的備選項之一。

游泳、健身瞭解一下：部落格、前端積累文件、公眾號、GitHub

VuePress特性：

  • 為技術文件而優化的 內建 Markdown 擴充
  • 在 Markdown 檔案中使用 Vue 元件的能力
  • Vue 驅動的自定義主題系統
  • 自動生成 Service Worker
  • Google Analytics 整合
  • 基於 Git 的 “最後更新時間”
  • 多語言支援
  • 預設主題包含：

建議先看一下官方文件

效果：

可能你會搭建出一個類似這樣的文件：

VuePress 手摸手教你搭建一個類Vue文件風格的技術文件/部落格

VuePress 手摸手教你搭建一個類Vue文件風格的技術文件/部落格

搭建：

全域性安裝VuePress

yarn global add vuepress # 或者：npm install -g vuepress
複製程式碼

新建資料夾

可以手動右鍵新建，也可以使用下面的命令新建資料夾：

mkdir project
複製程式碼

專案初始化

進入到project資料夾中，使用命令列初始化專案:

yarn init -y # 或者 npm init -y
複製程式碼

將會建立一個package.json檔案，長這樣子：

{
  "name": "project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}
複製程式碼

在project的根目錄下新建docs資料夾：

這個文件將作為專案文件的根目錄來使用：

mkdir docs
複製程式碼

在docs資料夾下建立.vuepress資料夾：

mkdir .vuepress
複製程式碼

所有 VuePress 相關的檔案都將會被放在這裡

在.vuepress資料夾下面建立config.js:

touch config.js
複製程式碼

config.js是VuePress必要的配置檔案，它匯出一個javascript物件。

你可以先加入如下配置：

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around'
}
複製程式碼

在.vuepress資料夾下面建立public資料夾:

mkdir public
複製程式碼

這個資料夾是用來放置靜態資源的，打包出來之後會放在.vuepress/dist/的根目錄。

首頁(像VuePress文件主頁一樣)

在docs資料夾下面建立一個README.md：

預設的主題提供了一個首頁，像下面一樣設定home:true即可，可以把下面的設定放入README.md中，待會兒你將會看到跟VuePress一樣的主頁。

---
home: true
heroImage: /logo.jpg
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
---
複製程式碼

ps：你需要放一張圖片到public資料夾中。

我們的專案結構已經搭好了：

project
├─── docs
│   ├── README.md
│   └── .vuepress
│       ├── public
│       └── config.js
└── package.json
複製程式碼

在 package.json 裡新增兩個啟動命令:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
複製程式碼

啟動你的VuePress：

預設是localhost:8080埠。

yarn docs:dev # 或者：npm run docs:dev
複製程式碼

構建：

build生成靜態的HTML檔案,預設會在 .vuepress/dist 資料夾下

yarn docs:build # 或者：npm run docs:build
複製程式碼

基本配置：

最標準的當然是官方文件,可以自己的需求來配置config.js。

可以參考一下我的config.js的配置：

module.exports = {
  title: '網站標題',
  description: '網站描述',
  // 注入到當前頁面的 HTML <head> 中的標籤
  head: [
    ['link', { rel: 'icon', href: '/favicon.ico' }], // 增加一個自定義的 favicon(網頁標籤的圖示)
  ],
  base: '/web_accumulate/', // 這是部署到github相關的配置 下面會講
  markdown: {
    lineNumbers: true // 程式碼塊顯示行號
  },
  themeConfig: {
    sidebarDepth: 2, // e'b將同時提取markdown中h2 和 h3 標題，顯示在側邊欄上。
    lastUpdated: 'Last Updated' // 文件更新時間：每個檔案git最後提交的時間
  }
};
複製程式碼

導航欄配置：

VuePress 手摸手教你搭建一個類Vue文件風格的技術文件/部落格

module.exports = {
  themeConfig: {
    nav:[
      { text: '前端演算法', link: '/algorithm/' }, // 內部連結 以docs為根目錄
      { text: '部落格', link: 'http://obkoro1.com/' }, // 外部連結
      // 下拉選單
      {
        text: 'GitHub',
        items: [
          { text: 'GitHub地址', link: 'https://github.com/OBKoro1' },
          {
            text: '演算法倉庫',
            link: 'https://github.com/OBKoro1/Brush_algorithm'
          }
        ]
      }        
    ]
  }
}
複製程式碼

側邊欄配置：

側邊欄的配置相對麻煩點，我裡面都做了詳細的註釋，仔細看，自己鼓搗鼓搗 就知道怎麼搞了。

module.exports = {
  themeConfig: {
      sidebar:{
        // docs資料夾下面的accumulate資料夾 文件中md檔案 書寫的位置(命名隨意)
        '/accumulate/': [
            '/accumulate/', // accumulate資料夾的README.md 不是下拉框形式
            {
              title: '側邊欄下拉框的標題1',
              children: [
                '/accumulate/JS/test', // 以docs為根目錄來查詢檔案 
                // 上面地址查詢的是：docs>accumulate>JS>test.md 檔案
                // 自動加.md 每個子選項的標題 是該md檔案中的第一個h1/h2/h3標題
              ]
            }
          ],
          // docs資料夾下面的algorithm資料夾 這是第二組側邊欄 跟第一組側邊欄沒關係
          '/algorithm/': [
            '/algorithm/', 
            {
              title: '第二組側邊欄下拉框的標題1',
              children: [
                '/algorithm/simple/test' 
              ]
            }
          ]
      }
  }
}
複製程式碼

其他：

程式碼塊編譯錯誤：

像下面這段程式碼會導致編譯錯誤，VuePress會去找裡面的變數，把它編譯成text：

{{}} 啦 {{}}
複製程式碼

所以我們的程式碼塊要以這種形式書寫：

//```js
{{}} 啦 {{}} // 註釋需要開啟 這樣vuepress會把這裡麵包裹的當成程式碼塊而不是js
//```
複製程式碼

並且這樣也會讓我們的程式碼高亮顯示(下圖第一個沒有高亮，第二個有高亮)，閱讀體驗更好：

VuePress 手摸手教你搭建一個類Vue文件風格的技術文件/部落格

自定義容器瞭解一下：

VuePress 手摸手教你搭建一個類Vue文件風格的技術文件/部落格

更改標題：

::: tip 替換tip的標題
這裡是內容。
:::
複製程式碼

其實文件裡有，我這裡只是提一下。

支援Emoji

VuePress 手摸手教你搭建一個類Vue文件風格的技術文件/部落格

文件中只提了支援Emoji,我在GitHub上找到了Emoji的列表，分享一下。

一個命令列釋出到github上：

在 docs/.vuepress/config.js 中設定正確的 base:

如果你打算髮布到 https://<USERNAME>.github.io/，則可以省略這一步，因為 base 預設即是 "/"。

如果你打算髮布到 https://<USERNAME>.github.io/<REPO>/（也就是說你的倉庫在 https://github.com/<USERNAME>/<REPO>），則將 base 設定為 "/<REPO>/"。

module.exports = {
  base: '/test/', // 比如你的倉庫是test
}
複製程式碼

建立腳步檔案:

在project的根目錄下，建立一個deploy.sh檔案：

#!/usr/bin/env sh

# 確保指令碼丟擲遇到的錯誤
set -e

# 生成靜態檔案
npm run docs:build

# 進入生成的資料夾
cd docs/.vuepress/dist

# 如果是釋出到自定義域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果釋出到 https://<USERNAME>.github.io  USERNAME=你的使用者名稱 
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果釋出到 https://<USERNAME>.github.io/<REPO>  REPO=github上的專案
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

cd -
複製程式碼

設定package.json：

{
  "scripts": {
    "d": "bash deploy.sh"
  }
}
複製程式碼

部署：

然後你每次可以執行下面的命令列，來把最新更改推到github上：

    npm run d
複製程式碼

如果你對執行專案和構建專案的命令列覺得很煩，你也可以像我這麼做：

"scripts": {
    "dev": "vuepress dev docs", // 本地執行專案 npm run dev
    "build": "vuepress build docs", // 構建專案 nom run build
    "d": "bash deploy.sh" // 部署專案 npm run d
  },
複製程式碼

更多：

實際上VuePress的配置、用法還有很多，像還可以配置PWA，以及在markdown裡面使用Vue元件等，這些功能我也還在摸索，所以大家一定要去看文件!

結語

上面已經寫得儘可能詳細了，我遇到的坑都寫上去了。搭建起來確實很簡單，心動不如行動，隨手花一兩個小時搭建一下又不吃虧，何樂而不為？

希望看完的朋友可以點個喜歡/關注，您的支援是對我最大的鼓勵。

部落格、前端積累文件、公眾號、GitHub

以上2018.9.9

相關文章