使用VuePress搭建文檔

前言

公司交給我一個任務，搭建一個公司內部的前端文檔，調研一番後，準備使用VuePress開發。固然，網上關於VuePress的好文章有很是多，原本不必再寫一篇了；可是，寫文章畢竟是對本身學習的一個總結，仍是寫一篇吧！

本文基於VuePress 1.x

官方文檔

VuePress

項目初始化

建立文件夾，生成.json文件

// 建立文件夾
mkdir docs

// 項目初始化 
npm init
複製代碼

安裝配置VuePress

// 進入
cd docs

// 項目安裝VuePress
npm install -D vuepress

// 新建文件夾，'docs'不能改爲別的名字，否則啓動報錯，
// error: 'no such file or directory, stat 'F:\web\docs\docs''
mkdir docs

// 新建一個 Markdown 文件
echo "# Hello VuePress!" > docs/README.md

// 啓動預覽
npx vuepress dev docs
複製代碼

在瀏覽器輸入http://localhost:8080/，能看到Hello VuePress!就表示啓動成功了

而後，配置package.json

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

配置後，從新啓動

npm run docs:dev
複製代碼

刷新瀏覽器，還能夠看到Hello VuePress!表示配置成功了

測試生成靜態HTML

npm run docs:build
複製代碼

在docs文件夾下面多了.vuepress文件夾，.vuepress文件夾下面有個dist文件夾，裏面結構以下

|-assets
    └──css
    └──img
    └──js
|-404.html
|-index.html

複製代碼

右鍵index.html在瀏覽器打開，你會發現樣式有錯誤，這個的緣由是路徑的問題，咱們設置一下，而後放到服務器上就行了

// 進入
cd .vuepress

// 建立配置文件
vim config.js

// 配置以下
module.exports = {
  // 設置網站標題
  title: '前端文檔', 
  // 設置輸出目錄
  dest: './dist', 
  // 設置站點根路徑，若是你在訪問的地址是 'www.xxxx.com/wxDocs' 那麼就設置成 '/wxDocs/'  
  base: '/wxDocs/' 
  // 添加 github 連接，可是這個要放在公司的內網服務器，因此爲空
  // repo: '' 
}

// 打包
npm run docs:build
複製代碼

你會發如今項目的根目錄多了一個dist文件夾，把這個文件夾裏面的全部東西上傳到服務器，同時刪除.vuepress文件夾下的dist文件夾

配置icon

// 進入
cd .vuepress

// 建立文件夾
mkdir public
複製代碼

使用在線ps打開一張圖片，更改圖像大小爲16*16 或者 32*32 或者64*64px，保存爲ico格式，複製到public下面

更改config.js，添加以下代碼

head: [['link', { rel: 'icon', href: '/logo.ico' }]]
複製代碼

從新啓動，刷新瀏覽器，看到瀏覽器導航欄出現圖標，表示配置成功

配置首頁

若是你想徹底自定義首頁，那麼就這樣：

cd .vuepress

// 建立文件夾
mkdir components

// 建立首頁文件，以正常寫vue的方式在 'login.vue' 寫代碼
vim login.vue
複製代碼

而後在README.md文件中修改成：

---
layout: login
---

<login />

複製代碼

layout開啓自定義設置，目標連接到你自定義的 login.vue 頁面，而後下面的 <login /> 引入

若是不想自定義，那麼使用默認的就能夠了，這個是VuePress官方的默認配置首頁

我這裏考慮到到是內部文檔，不開放給大衆，上傳到服務器，大衆用戶有可能會在搜索平臺莫名搜索到文檔地址，因此須要一個登陸頁面，須要自定義一個登陸的首頁，選擇了layout使用vue徹底自定義

寫好頁面UI後，就能夠寫登陸跳轉邏輯了，首先，在項目docs文件夾下新建文件夾：

// 在根目錄新建home文件夾
mkdir home

// 進入
cd home 

// 新建 'README.md' 文件，必需要有，VuePress會自動把文件夾裏的 'README.md' 轉換爲 'index.html' 文件，有這個才能跳轉
vim README.md
複製代碼

新建好後項目結構以下：

|-dist
|-docs
    └──.vuepress
    └──home
        └──README.md
    └──README.md
|-node_modules
|-package-lock.json
|-package.json
複製代碼

而後給你登陸的按鈕綁上一個click

methods: {
    goHome() {
      // 判斷帳號密碼是否正確的邏輯
      ...
      // 正確，跳轉
      this.$router.push({ path: "/home/index.html" });
    }
  }
複製代碼

這樣你的首頁就配置好了

配置導航

VuePress配置導航很是簡單，只須要在config.js添加以下代碼：

module.exports = {
  themeConfig: {
    nav: [
      {
        text: '首頁',
        link: '/home/'
      },
      {
        text: 'H5',
        link: '/H5/'
      },
      {
        text: '規範',
        link: '/Standard/'
      }
      ...
    ]
  }
}

複製代碼

而後在項目docs文件夾下新建和link一一對應的文件夾，文件夾下新建README.md就能夠了

建好後，重啓，刷新瀏覽器查看效果

tips：新建的文件夾和上面創建的home文件夾平級

配置側邊欄

配置側邊欄也很是的簡單，首先配置config.js

module.exports = {
  themeConfig: {
    sidebar: {
      '/H5/': [
        'H5和app對接文檔',
        '管理後臺開發文檔'
      ],
      '/Standard/': [
        'H5開發規範',
        'H5版本管理規範'
      ]
    }
  }
}
複製代碼

而後，在對應的文件夾下新建.md文件就能夠了，如：

|-h5
    └──H5和app對接文檔.md
    └──管理後臺開發文檔.md
    └──README.md
|-Standard
    └──H5開發規範.md
    └──H5版本管理規範.md
    └──README.md

複製代碼

tips: 你在config.js裏配置的名字，要和你在文件夾下新建的名字一致，可是實際側邊欄的名字，是你在H5和app對接文檔.md文件下寫的第一個標題的名字

從新啓動，刷新瀏覽器，你會看到設置已經生效的，可是貌似仍是有點問題，你在.md文件下生成的每個標題都會生成一個二級的頁面，設置config.js取消掉

module.exports = {
  themeConfig: {
    sidebarDepth: '0',
  }
}
複製代碼

個性化定製

在config.js裏添加

module.exports = {
  // 代碼塊顯示行號
  markdown: {
    lineNumbers: true
  },
}
複製代碼

文檔的滾動條太醜了，改一個樣子

// 進入
cd .vuepress

// 新建'styles'文件夾
mkdir styles

// 新建 'index.styl' 和 'palete.styl'，VuePress使用 'stylus' 預處理器
vim index.styl
vim palete.styl
複製代碼

index.styl 爲全局自定義的樣式，權限在默認之上
palete.styl 覆蓋默認的主題配置

index.styl 樣式

/*定義滾動條高寬及背景 高寬分別對應橫豎滾動條的尺寸*/
::-webkit-scrollbar
{
  width: 8px;
  height: 8px;
  border-radius: 10px;
  background-color: #F5F5F5;
}

/*定義滾動條軌道 內陰影+圓角*/
::-webkit-scrollbar-track
{
  border-radius: 10px;
  -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.3);
  background-color: #F5F5F5;
}

/*定義滑塊 內陰影+圓角*/
::-webkit-scrollbar-thumb
{
  border-radius: 10px;
  -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,.3);
  border-radius: 10px;
  /* 線性漸變 */
  background-image: -webkit-gradient(linear, 
  left bottom, left top,
   color-stop(0.44, rgb(60,186,146)), 
   color-stop(0.72, rgb(253,187,45)), 
   color-stop(0.86, rgb(253,187,45)));
  transition: 0.3s ease-in-out;
}
/*定義滑塊懸浮樣式*/
::-webkit-scrollbar-thumb:hover{
  background-image: -webkit-gradient(linear, 
  left bottom, left top, 
  color-stop(0.44, rgb(253,187,45)), 
  olor-stop(0.72, rgb(253,187,45)), 
  color-stop(0.86, rgb(60,186,146)));
  transition: 0.3s ease-in-out;
}

.site-name{
  background-image: -webkit-linear-gradient(left,
   #22c1c3, #fdbb2d 25%, #22c1c3 50%, #fdbb2d 75%, #22c1c3);
  -webkit-text-fill-color: transparent;
  -webkit-background-clip: text;
  -webkit-background-size: 200% 100%;
  -webkit-animation: myGradientChange 4s infinite linear;
  animation: myGradientChange 4s infinite linear;
}
@keyframes myGradientChange  {
  0%{ background-position: 0 0;}
  100% { background-position: -100% 0;}
}
複製代碼

palete.styl 樣式

// 點擊狀態
$accentColor = #3eaf7c

// 文字
$textColor = #2c3e50

// 邊框
$borderColor = #eaecef

// 代碼背景
$codeBgColor = #282c34
複製代碼

若是你想要單獨爲某個頁面寫一個樣式，能夠這樣

// 如今某一個頁面的 '.md' 文件上添加
---
pageClass: custom-page-class
---
複製代碼

而後在 index.styl 中添加

.theme-container.custom-page-class {
  /* page-specific rules */
}
複製代碼

最後

VuePress總體上來講仍是比較簡單的，想寫出新意來真的很是困難！

so，只能這樣了。

參考

vuepress爬坑之旅
VuePress 快速踩坑
VuePress博客搭建筆記（二）個性化配置