由於本身平時常常寫博客,也有博客網站,因此 Leader 叫我作一個 CMS
的幫助中心的技術選型,CMS
的幫助中心的功能:是經過文章來教用戶如何使用咱們的項目。css
因此筆者要作一個靜態網站的技術選型,筆者把網上流行的 VuePress
和 GitBook
兩種方式都嘗試了一下,並作了對比,這裏寫篇文章總結一下,順便把本身的博客網站重做一便,哈哈。html
優惠消息:雙 12,阿里服務器新用戶 1 折,老用戶 5 折:筆者以爲每一個開發者都應該擁有本身的網站和服務器,這但是很酷的事情,學習 Linux、跑跑腳本、建站、搭博客啥的都行,如今阿里雲的服務器只須要 89元
一年,一塊兒參與瓜分 60 萬現金,優惠只剩下最後幾天了,須要的趕快上車了,錯過還須要再等一年。前端
VuePress 是 Vue
驅動的靜態網站生成器。vue
簡潔至上node
以 Markdown
爲中心的項目結構,以最少的配置幫助你專一於寫做。webpack
Vue 驅動git
享受 Vue + webpack
的開發體驗,能夠在 Markdown
中使用 Vue
組件,又可使用 Vue
來開發自定義主題。github
高性能web
VuePress
會爲每一個頁面預渲染生成靜態的 HTML
,同時,每一個頁面被加載的時候,將做爲 SPA
運行。npm
首頁:
評論:
效果詳情請看:https://biaochenxuying.github.io/blog/ 。
像數 1, 2, 3 同樣容易
# 安裝 yarn global add vuepress # 或者:npm install -g vuepress # 建立項目目錄 mkdir vuepress-starter && cd vuepress-starter # 新建一個 markdown 文件 echo '# Hello VuePress!' > README.md # 開始寫做 vuepress dev . # 構建靜態文件 vuepress build .
VuePress 遵循 「約定優於配置」 的原則,推薦的目錄結構以下:
├── docs │ ├── .vuepress (可選的) │ │ ├── components (可選的) │ │ ├── theme (可選的) │ │ │ └── Layout.vue │ │ ├── public (可選的) │ │ ├── styles (可選的) │ │ │ ├── index.styl │ │ │ └── palette.styl │ │ ├── templates (可選的, 謹慎配置) │ │ │ ├── dev.html │ │ │ └── ssr.html │ │ ├── config.js (可選的) │ │ └── enhanceApp.js (可選的) │ │ │ ├── README.md │ ├── guide │ │ └── README.md │ └── config.md │ └── package.json
注意:請留意目錄名的大寫。
docs/.vuepress
: 用於存放全局的配置、組件、靜態資源等。docs/.vuepress/components
: 該目錄中的 Vue
組件將會被自動註冊爲全局組件。docs/.vuepress/theme
: 用於存放本地主題。docs/.vuepress/styles
: 用於存放樣式相關的文件。docs/.vuepress/styles/index.styl
: 將會被自動應用的全局樣式文件,會生成在最終的 CSS
文件結尾,具備比默認樣式更高的優先級。docs/.vuepress/styles/palette.styl
: 用於重寫默認顏色常量,或者設置新的 stylus
顏色常量。docs/.vuepress/public
: 靜態資源目錄。docs/.vuepress/templates
: 存儲 HTML
模板文件。docs/.vuepress/templates/dev.html
: 用於開發環境的 HTML
模板文件。docs/.vuepress/templates/ssr.html
: 構建時基於 Vue SSR
的 HTML
模板文件。docs/.vuepress/config.js
: 配置文件的入口文件,也能夠是 YML
或 toml
。docs/.vuepress/enhanceApp.js
: 客戶端應用的加強。注意:
templates/ssr.html
或 templates/dev.html
時,最好基於 默認的模板文件 來修改,不然可能會致使構建出錯。templates/ssr.html
和 templates/dev.html
是有添加以下這一行代碼的:<meta id="referrer" name="referrer" content="never" />
由於筆者的圖片都是存在簡書上的,因此爲了能夠訪問第三方圖牀的圖片,才添加了這句代碼,若是你的圖片是存在本地的,去掉這句代碼便可,至於具體緣由請看筆者寫的文章:前端解決第三方圖片防盜鏈的辦法 - html referrer 訪問圖片資源403問題 。
評論功能用了 GitTalk。
具體實踐以下:
Client ID
&& Client Secret
建立成功有 Client ID
和 Client Secret
,保存下來,後面咱們會用到。
Vuepress
默認 .vuepress / components
文件夾下的組件會全局註冊,所以咱們建立一個 comment 組件。
gittalk.css 請點擊 這裏
<template> <div class="gitalk-container"> <div id="gitalk-container"></div> </div> </template> <script> export default { name: 'comment', data() { return {}; }, mounted() { let body = document.querySelector('.gitalk-container'); let script = document.createElement('script'); script.src = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js'; body.appendChild(script); script.onload = () => { const commentConfig = { clientID: '你的clientID', clientSecret: '你的clientSecret', repo: '你的倉庫名稱', owner: '你的用戶名', // 這裏接受一個數組,能夠添加多個管理員,能夠是你本身 admin: ['管理用戶名'], // id 用於當前頁面的惟一標識,通常來說 pathname 足夠了, // 可是若是你的 pathname 超過 50 個字符,GitHub 將不會成功建立 issue,此狀況能夠考慮給每一個頁面生成 hash 值的方法. id: location.pathname, distractionFreeMode: false, }; const gitalk = new Gitalk(commentConfig); gitalk.render('gitalk-container'); }; }, }; </script> <style> @import '../css/gittalk.css'; </style>
理論上,咱們在每一個 markdown
文件裏直接加入這個組件便可,可是每次都添加有點麻煩,仍是讓 node
來幫咱們吧
根目錄建立 build
文件夾, 建立三個文件 addComponents.js
, delComponents.js
, findMarkdown.js
, 分別代碼以下:
// addComponents.js const fs = require("fs"); const findMarkdown = require("./findMarkdown"); const rootDir = "./docs"; findMarkdown(rootDir, writeComponents); function writeComponents(dir) { if (!/README/.test(dir)) { fs.appendFile(dir, `\n \n <comment/> \n `, err => { if (err) throw err; console.log(`add components to ${dir}`); }); } }
// delComponents.js const fs = require("fs"); const findMarkdown = require("./findMarkdown"); const rootDir = "./docs"; findMarkdown(rootDir, delComponents); function delComponents(dir) { fs.readFile(dir, "utf-8", (err, content) => { if (err) throw err; fs.writeFile( dir, content.replace(/\n \n <comment\/> \n /g, ""), err => { if (err) throw err; console.log(`del components from ${dir}`); } ); }); }
// findMarkdown.js const fs = require("fs"); function findMarkdown(dir, callback) { fs.readdir(dir, function(err, files) { if (err) throw err; files.forEach(fileName => { let innerDir = `${dir}/${fileName}`; if (fileName.indexOf(".") !== 0) { fs.stat(innerDir, function(err, stat) { if (stat.isDirectory()) { findMarkdown(innerDir, callback); } else { // 跳過readme 文件,固然你也能夠自行修改 if (/\.md$/.test(fileName) && !/README/.test(fileName)) callback(innerDir); } }); } }); }); } module.exports = findMarkdown;
修改 package.json
的 scripts
, 先爲每一個 md
文件添加組件,而後打包,最後再一一刪除 markdown
中的 comment
組件。
"build": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js",
筆者的項目裏面是把添加了二條命令的,好比 npm run dev:md
和 npm run build:md
纔是有評論組件的。
"scripts": { "dev": "vuepress dev docs", "dev:md": "node ./builds/addComponents.js && vuepress dev docs && node ./builds/delComponents.js", "docs:dev": "vuepress dev docs", "build": "vuepress build docs", "build:md": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js", "docs:build": "vuepress build docs", "delay": "bash delay.sh", "test": "echo \"Error: no test specified\" && exit 1" },
想要怎樣的打包命令,本身修改就行。
github
的 issues
的同步的話,還要在 issues
的 label
裏添加相應的 pathname
和 gitalk
,其中 pathname
就是評論組件裏面的 location.pathname
。好比個人:
當咱們將文檔寫好後就到了咱們最關心的地方了,怎麼將打包後的代碼推送到遠程倉庫的 gh-pages
分支上。
touch 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 # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master # 若是發佈到 https://<USERNAME>.github.io/<REPO> # git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages cd -
package.json
{ "scripts": { "deploy": "bash deploy.sh" }, }
npm run deploy // 便可自動構建部署到 github 上。
詳情移步 vuepress 官網 vuepress.vuejs.org。
效果:
效果詳情請看:http://biaochenxuying.cn:2021。
npm i gitbook-cli -g
gitbook init
gitbook install
gitbook serve
gitbook build
gitbook -help
gitbook -V
而後,咱們找個空文件夾,初始化一個 GitBook 項目。
gitbook init
初始化 README.md 和 SUMMARY.md 兩個文件.gitbook build
本地構建但不運行服務,默認輸出到 _book/ 目錄.gitbook serve
本地構建並運行服務,默認訪問 http://localhost:4000 實時預覽.- GitBook - README.md - SUMMARY.md
README.md
是默認首頁文件,至關於網站的首頁 index.html
,通常是介紹文字或相關導航連接.SUMMARY.md
是默認歸納文件,主要是根據該文件內容生成相應的目錄結構,同 README.md
同樣都是被 gitbook init
初始化默認建立的重要文件._book
是默認的輸出目錄,存放着原始 markdown
渲染完畢後的 html
文件,能夠直接打包到服務器充當靜態網站使用。通常是執行 gitbook build
或 gitbook serve
自動生成的.book.json
是配置文件,用於個性化調整 gitbook
的相關配置,如定義電子書的標題、封面、做者等信息。雖然是手動建立但通常是必選的.GLOSSARY.md
是默認的詞彙表,主要說明專業詞彙的詳細解釋,這樣閱讀到專業詞彙時就會有相應提示信息,也是手動建立可是可選的.LANGS.md
是默認的語言文件,用於國際化版本翻譯和 GLOSSARY.md
同樣是手動建立可是可選的.book.json 的意思:
title
:網站標題author
:網站做者description
:網站功能描述language
:網站使用語言styles
:網站額外配置的樣式表plugins
:網站使用的插件pluginsConfig
:網站使用的插件的額外配筆者的 book.json
:
{ "title": "夜盡天明的博客", "author": "biaochenxuying", "description": "大前端技術爲主,讀書筆記、隨筆、理財爲輔,作個終身學習者。", "language": "zh-hans", "plugins": [ "-highlight", "copy-code-button", "search-pro", "-search", "-lunr", "expandable-chapters", "splitter", "-sharing", "github-buttons", "donate", "tbfed-pagefooter", "baidu-tongji", "anchor-navigation-ex" ], "pluginsConfig": { "github-buttons": { "buttons": [ { "user": "biaochenxuying", "repo": "blog", "type": "star", "count": true, "size": "small" }, { "user": "biaochenxuying", "width": "160", "type": "follow", "count": true, "size": "small" } ] }, "donate": { "button": "打賞", "wechatText": "微信打賞", "wechat": "https://camo.githubusercontent.com/ee094d402f957e5d656a399b9dc50ff8c010114e/68747470733a2f2f75706c6f61642d696d616765732e6a69616e7368752e696f2f75706c6f61645f696d616765732f31323839303831392d666661623762643234643038633030642e6a7065673f696d6167654d6f6772322f6175746f2d6f7269656e742f7374726970253743696d61676556696577322f322f772f31323430" }, "tbfed-pagefooter": { "copyright":"Copyright © biaochenxuying.cn 2019", "modify_label": "該文件修訂時間:", "modify_format": "YYYY-MM-DD HH:mm:ss" }, "baidu-tongji": { "token": "XXXXX" }, "anchor-navigation-ex": { "showLevel": false } } }
插件的配置能夠說是 GitBook 的核心。
詳情能夠看 GitBook - 快速打造可留言的博客,這裏就不展開講了。
相同點
markdown
格式,圖片、視頻 等靜態資源能夠保存在本地,或者保存到容許訪問的第三方服務商(如七牛雲);world
文檔或者 html
格式,要轉換成 md
格式才行。world
文檔轉換成 md 格式的工具,都很差用,特別是有原文檔有圖片的時候。不一樣點
GitBook
的配置成本很小,能夠本地編輯,而後直接部署;GitBook
官方還有個在線編輯器,不過內容要存在 GitBook
的服務器上。VuePress
的配置成本稍稍大一點,不過可使用 Vue
的語法與組件,定製化更自由一點,並且 VuePress
中編寫 Vue
和平時同樣,學習成本幾乎爲零,能夠本地用 VsCode 編輯,而後直接命令行部署。結論
markdown
語法來寫文章,markdown
也就幾個經常使用語法而已,很是簡單上手。GitBook
,技術人員推薦用 VuePress
,特別是前端技術人員。VuePress
。本文中使用 VuePress
和 GitBook
的搭建的完整示例代碼都已經上傳到 GitHub
上了,能夠自行下載來用。
只要把其中的一些配置信息換成本身的就行,好比 倉庫
、Client ID
&& Client Secret
、做者等。
源碼地址: https://github.com/biaochenxuying/blog 。
其中 VuePress
和 GitBook
的示例代碼都在 blog-gitbook
和 blog-vuepress
裏面了。
此次需求的結果
令筆者吐血的是:花了 3 天搞的調研,最後 leader 沒有采用 😭,仍是用回了 功能很重的 wordpress
。
由於非技術人員要用起來的話,學習成本是比較大的 😂,好比要學 markdown 語法
、ide 編輯器
、基本的打包命令、可能還要學 git
,而非技術人員編輯文檔時,通常是用 wps
的 😂。
比較欣慰的是:筆者作完調研後,本身的博客網站也能用上了,哈哈。
推薦閱讀:GitHub 上能挖礦的神仙技巧 - 如何發現優秀開源項目,估計不少人都不知道的技巧,甚至不少高級工程師都不知道。
參考文章:爲你的 VuePress 博客添加 GitTalk 評論