VuePress 手摸手教你搭建一個類Vue文檔風格的技術文檔/博客

時間 2019-11-07

標籤 vuepress 搭建一個 vue 文檔風格技術博客简体版

原文原文鏈接

前言：

VuePress是尤大爲了支持 Vue 及其子項目的文檔需求而寫的一個項目，VuePress界面十分簡潔，而且很是容易上手，一個小時就能夠將項目架構搭好。如今已經有不少這種類型的文檔，若是你有寫技術文檔的項目的話，VuePress絕對能夠成爲你的備選項之一。javascript

VuePress特性：

爲技術文檔而優化的內置 Markdown 拓展
在 Markdown 文件中使用 Vue 組件的能力
Vue 驅動的自定義主題系統
自動生成 Service Worker
Google Analytics 集成
基於 Git 的「最後更新時間」
多語言支持
默認主題包含：

建議先看一下官方文檔html

效果：

可能你會搭建出一個相似這樣的文檔：前端

搭建：

全局安裝VuePress

yarn global add vuepress # 或者：npm install -g vuepress

新建文件夾

能夠手動右鍵新建，也可使用下面的命令新建文件夾：vue

mkdir project

項目初始化

進入到project文件夾中，使用命令行初始化項目:java

yarn init -y # 或者 npm init -y

將會建立一個package.json文件，長這樣子：webpack

{
  "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文件夾：

這個文檔將做爲項目文檔的根目錄來使用：git

mkdir docs

在docs文件夾下建立`.vuepress`文件夾：

mkdir .vuepress

全部 VuePress 相關的文件都將會被放在這裏github

在`.vuepress`文件夾下面建立`config.js`:

touch config.js

config.js是VuePress必要的配置文件，它導出一個javascript對象。web

你能夠先加入以下配置：面試

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最後提交的時間
  }
};

導航欄配置：

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
//```

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

自定義容器瞭解一下：

更改標題：

::: tip 替換tip的標題
這裏是內容。
:::

其實文檔裏有，我這裏只是提一下。

支持Emoji

文檔中只提了支持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組件等，這些功能我也還在摸索，因此你們必定要去看文檔!