為什麼選擇vuepress
部落格地址 程式設計師成長指北(http://www.inode.club/) 可以先體驗下。
之前使用docsify部署過個人部落格, 在此之前也使用過gitbook, 這次使用vuepress來改版, 根據自己的體驗, 將這三者做一個對比
從閱讀體驗來說(個人感覺): gitbook > docsify =vuepress從配置上來說, docsify相比於vuepress和gitbook都要簡單一些.從效能上來說: vuepress > docsify雖然docsify也是基於vue的, docsify是執行時解析, vuepress是預先渲染HTML靈活性上, vuepress也是相當佔優勢的, 對vue熟悉的朋友可以編寫vue元件實現你想要的功能樣式vuepress特性為技術文件而最佳化的內建Markdown拓展在Markdown檔案中使用Vue元件的能力Vue驅動的自定義主題系統自動生成Service Worker(支援PWA)Google Analytics整合基於Git的"最後更新時間多語言支援響應式佈局支援PWA模式總的來說, 使用vuepress優勢有挺多的, 特別是我之前使用docsify搭建的網站, 是一點也沒有被瀏覽器收錄啊, 怎麼都搜不到,受到一萬點打擊,所以決心改一改
專案搭建安裝vuepress第一步就是進行vuepress進行安裝: 如果使用npm來安裝, Node.js版本需要 >=8 才可以
yarn global add vuepress # 或者：npm install -g vuepress 注意
如果你的現有專案依賴了 webpack 3.x，推薦使用 Yarn而不是 npm 來安裝 VuePress。因為在這種情形下，npm 會生成錯誤的依賴樹。
初始化專案建立專案目錄blog
mkdir blog cd blog 初始化
yarn init -y # 或者 npm init -y 初始化完成後, 會建立一個package.json
{ "name":"blog", "version": "1.0.0", "main": "index.js", "license": "MIT" "scripts": { "test": "echo \"Error: no test specified\" && exit 1" } } 在package.json中, 配置啟動命令
"scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" } 啟動專案: npm run docs:dev這條命令就等於vuepress dev docs
打包專案: npm run build 這條命令就等於 vuepress build docs
建立docs目錄, 主要用於放置我們寫的.md型別的文章以及.vuepress相關的配置
mkdir docs 接著在docs資料夾中建立.vuepress資料夾
cd docs mkdir .vuepress 這個檔案主要就是放vuepress相關的配置
到這一步, 我們的專案大體架子已經搭建出來了,接下來進行配置.
頁面具體內容配置基本配置接下來要讓頁面顯示內容, 就需要進行配置, 新建一個總的配置檔案config.js, 這個檔案的名字是固定的.
cd .vuepress touch config.js config.js最基礎的配置檔案內容如下:
module.exports = { title: 'koala的部落格', description: '專注 Node.js 技術棧分享，從前端到Node.js再到資料庫', } 如果這時執行npm run docs:dev或者yarn docs:dev, 會出現頁面404頁面,vuepress預設開啟的是docs下的readme.md檔案, 由於你沒有建立,所以找到的是vuepress預設提供的404頁面, 關於這有點,我們藉助vue-devtools工具來檢視一下vue的結構
在docs目錄下建立README.md檔案, 再執行,就可以看到執行起來的效果, 如下圖所示:
blog001.jpg設定封面頁此時README檔案中沒有內容,封面頁是空的, 我們可以透過在這個markdown檔案中寫一些內容, 同時官方也給我們提供了封面頁的模板(個人覺得還是比較實用的):
--- home: true heroImage: /home.png actionText: Get Started → actionLink: /node/ features: - title: day day up details: 記錄每一天的進步, 一分耕耘，一分收穫. - title: 程式設計師成長指北 details: 專注 Node.js 技術棧分享，從 前端 到 Node.js 再到 後端資料庫，祝您成為優秀的高階 Node.js 全棧工程師 - title: koala details: 一個有趣的且樂於分享的人。座右銘：今天未完成的，明天更不會完成。 footer: MIT Licensed | Copyright © 2018-present Evan You --- 效果圖如下:
配置導航欄nav在config.js中新增:
themeConfig:{ nav: [{text: "主頁", link: "/" }, { text: "node", link: "/node/" }, { text: "前端", link: "/webframe/"}, { text: "資料庫", link: "/database/" }, { text: "android", link: "/android/" }, { text: "面試問題", link: "/interview/" } ], } 效果如下圖:
如果想要展示二級導航, 可以這樣配置:
themeConfig:{ nav: [{text: "主頁", link: "/" }, { text: "node", link: "/node/" }, { text: "前端", items: [ { text: "html", link:"/web/html/"}, { text: "css", link:"/web/css/"}, ] }, { text: "資料庫", link: "/database/" }, { text: "android", link: "/android/" }, { text: "面試問題", link: "/interview/" } ], } 效果如圖所示:
當你使用上面的方式配置nav時, 目錄結構最好和我建立的一樣 專案目錄結構如下:
導航欄建立好了, 接下來就是配置頁面內容中的側邊欄slider
配置側邊欄slider1.自動獲取側邊欄內容如果你希望自動生成當前頁面標題的側邊欄, 可以在config.js中配置來啟用
// .vuepress/config.js module.exports = { themeConfig:{ sidebar: 'auto', // sidebarDepth: 1 } } 如果你希望為不同的頁面組顯示不同的側邊欄, 就和官網一樣, 點選指南顯示的是對應的側邊欄,目前目錄有node \ database \ web等, 這些目錄下都存放著多個md檔案:
module.exports = { themeConfig:{ sidebar:{ "/node/":[ ["", "node目錄"], ["path", "作為前端也需要知道的路徑知識"], ["stream", "node核心模組-stream"] ], "/web/":[ ["", "前端"], { title: "css", name: "css", collabsable: false, children: [ ["css/", "目錄"], ['css/1', "css常考面試題"] ] } ] } } } 設定的效果圖如下: 在node導航下:
在前端導航下的效果:
上面採用了兩個方式配置側邊欄, 一個側邊欄是node目錄下直接是寫的markdown文章, 而在web下又有多個分類, 所有有進行了分欄配置, 其實這兩種方式在我們部落格中都是比較常見的
自定義佈局內容網站的導航和側邊欄都已經配置好之後, 如果你覺得頁面不是很符合你的預期, 你也可以自定修改成你想要的效果。比如就像我的部落格中左側固定的內容, 就是自定義的全域性元件. 這裡使用vuepress提供的外掛機制來實現
在.vuepress資料夾下建立components資料夾, 在components下再建立fixed.vue檔案
<template> <div class="fixed_container"> <div class="tencent_code"> <h4>關注作者公眾</h4> <p>和萬千小夥伴一起學習</p> <img src="/ggh.jpg" alt=""> </div> <div class="group_code"> <h4>加入技術交流群</h4> <p>掃描二維碼 備註 <span> 加群</span> </p> <img src="/wechat.jpg" alt=""> </div> </div> </template> <script> export default { name: 'fixed' } </script> .... // 這裡省略了部分樣式程式碼, 想看全部的小夥伴點開github地址就可以了 然後在配置檔案中以外掛的形式配置即可:
// 外掛 plugins:[ { name:"page-plugin", globalUIComponents:["fixed"], } ]globalUIComponents是用於注入全域性的UI, 它以陣列的形式接收引數名字, 這裡的名字必須與components資料夾下的.vue檔案同名, 全域性UI就是一個Vue元件; 其實vuepress也提供了一些內建的全域性UI元件, 例如:back-to-top, popup, nprogress等.
配置外掛UI外掛配置內建的全域性UI,首先需要外掛:
yarn add -D @vuepress/plugin-back-to-top @vuepress/plugin-nprogress # OR npm install -D @vuepress/plugin-back-to-top @vuepress/plugin-nprogress 在config.js中配置:
plugins:[ ["@vuepress/back-to-top"], // 返回頂部 ["@vuepress/nprogress"], // 載入進度條 ]這裡需要注意一點就是看你專案中是否安裝了vuepress, 由於我之前是全域性安裝的, 在專案下還沒有安裝, 外掛是依賴於vuepress的, 所有沒有安裝的需要安裝上, 外掛才有效.
支援PWAvuepress還有一個我比較看重的優勢, 就是支援PWA, 當用戶沒有網的情況下,一樣能繼續的訪問我們的網站
在0.x 版本中我們只要配置serviceWorker: true 即可, 但是我們現在使用的是1.2.0版本, 這個版本中已經將這個功能抽離出來作為外掛的方式使用, 下面就看一下具體如何使用的:
首先需要安裝外掛:
yarn add -D @vuepress/plugin-pwa # 或者 npm install -D @vuepress/plugin-pwa 在config.js中配置:
module.exports = { plugins: ['@vuepress/pwa', { serviceWorker: true, updatePopup: true }] } 注意點:
為了讓你的網站完全地相容 PWA，你需要:
在 .vuepress/public 提供 Manifest 和 icons
在 .vuepress/config.js 新增正確的 head links
// 配置 module.exports = { head: [ ['link', { rel: 'icon', href: `/favicon.ico` }], //增加manifest.json ['link', { rel: 'manifest', href: '/manifest.json' }], ], } manifest.json 檔案
但是我後面也會將gitTalk配置方式寫出來, 方便使用gitTalk的小夥伴
然後建立應用, 獲取APP ID 和APP KEY
應用建立好以後，進入剛剛建立的應用，選擇左下角的設定 > 應用Key，然後就能看到你的APP ID 和APP Key了
安裝:yarn add vuepress-plugin-comment -D
快速使用在.vuepress下的config.js外掛配置中:
module.exports = { plugins: [ [ 'vuepress-plugin-comment', { choosen: 'valine', // options選項中的所有引數，會傳給Valine的配置 options: { el: '#valine-vuepress-comment', appId: 'Your own appId', appKey: 'Your own appKey' } } ] ] } appid和appkey為你建立的應用的APP ID 和APP Key
gitTalk 使用主題樣式修改vuepress預設是主題顏色是綠色, 如果你不喜歡可以對其進行更改. 如果要對預設設定的樣式進行簡單顏色替換, 或者自定義一些顏色變數供以後使用, 可以在.vuepress/styles下建立palette.styl檔案.
你可以調整的顏色變數:
// 顏色 $textColor ?= #2c3e50 $accentColor ?= #1e90ff $grayTextColor ?= #666 $lightTextColor ?= #999 $borderColor ?= #eaecef $codeBgColor ?= #282c34 $arrowBgColor ?= #ccc $navbarColor ?= #fff $headerColor ?= #fff $headerTitleColor ?= #fff $nprogressColor ?= $accentColor // 佈局 $navbarHeight ?= 3.6rem $bannerHeight ?= 12rem // 響應式 breakpoints $MQWide ?= 1440px $MQNarrow ?= 1024px $MQMobile ?= 768px $MQMobileNarrow ?= 480px 注意點:
你應該只在這個檔案中寫入顏色變數。因為 palette.styl 將在根的 stylus 配置檔案的末尾引入，作為配置，它將被多個檔案使用，所以一旦你在這裡寫了樣式，你的樣式就會被多次複製
如果要新增額外的樣式, vuepress也是提供了簡便方法的, 只要在.vuepress/styles檔案下建立一個 index.styl, 在裡面寫css樣式即可, 注意檔案命名是固定的.
部署nginx部署我的部落格採用的是靜態檔案部署, 感覺方便又便捷, 之前部署在Github Pages上, 訪問速度不是很理想.
第一步: 確保你滿足下面幾個條件
你有一臺伺服器已經安裝好nginx, 如果不會的小夥伴請看如何安裝nginx解析了一個可用的域名第二步: 打包你的專案
執行npm run docs:build將專案打包, 預設打包檔案在docs/.vuepress/dist目錄下
第三步: 配置nginx
進入到nginx 配置目錄, 找到conf.d檔案, 新增下面的配置:
server { listen 80; server_name www.inode.club; root /usr/web/inode/dist; error_log /var/log/nginx/inode-error.log; access_log /var/log/nginx/inode-access.log; # deny all; index index.php index.html index.htm; } **第四步: 上傳靜態資原始檔 **
將靜態資原始檔放置到伺服器上, 路徑為配置的/usr/web/inode/dist, 可以藉助xftp工具上傳也可以透過git克隆, 選擇適合自己的方式就可以
**第五步: 重啟nginx **
# 重啟之前務必檢查配置是否正確 sudo nginx -t // 檢查配置 sudo nginx -s reload // 重啟 然後你就可以透過域名來訪問你的網站啦!
github部署將程式碼部署到 Github Pages, 你可以看vuepress文件: vuepress部署, 也參照我這裡寫的的步驟來部署
第一步: 首先確保你的專案滿足以下幾個條件:
文件放置在docs目錄中使用的是預設的構建輸出位置vuepress以本地依賴的形式被安裝到你的專案中, 在根目錄package.json檔案中包含如下程式碼:// 配置npm scripts "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" } // VuePress 以本地依賴的形式被安裝 "devDependencies": { "vuepress": "^1.2.0" } 第二步: 建立github倉庫
在github上建立一個名為blog的倉庫, 並將程式碼提交到github上
第三步: 配置倉庫名稱
配置docs/.vuepress/config.js檔案中的base, 如果打算髮布到https://<USERNAME>.github.io/<REPO>/(也就是說你的倉庫在: https://github.com/<USERNAME>/<REPO> ), 此處我的倉庫為: blog, 則將base按照如下配置即可:
module.exports = { base: "/blog/" } 第四步: 在專案根目錄中,建立一個如下的指令碼檔案deploy.sh
#!/usr/bin/env sh # 確保指令碼丟擲遇到的錯誤 set -e # 生成靜態檔案 npm run docs:build # 進入生成的資料夾 cd docs/.vuepress/dist git init git add -A git commit -m 'deploy' # 如果釋出到 https://<USERNAME>.github.io/<REPO> git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages # 例如 git push -f [email protected]:koala-coding/blog.git master:gh-pages cd - 第五步: 雙擊 deploy.sh 執行指令碼
會自動在我們的 GitHub 倉庫中，建立一個名為 gh-pages 的分支，而我們要部署到 GitHub Pages 的正是這個分支