文檔如何自動(dòng)化部署到線上環(huán)境「每個(gè)前端都可以擁有自己的博客」
前言
說起文檔，我們可能會(huì)第一時(shí)間會(huì)想起很多技術(shù)文檔，比如Vue.js文檔、React.js文檔、TypeScript文檔，它們都有相似的布局和樣式。
那么，作為開發(fā)者的我們，怎么不也搞一個(gè)類似于技術(shù)文檔的網(wǎng)站作為自己的博客呢?現(xiàn)在有很多開源的項(xiàng)目可以做博客，比如基于Vue.js開發(fā)的Vuepress以及同一家的Vitepress，還有基于React.js開發(fā)的Docusaurus。這么多方案，我們今天就拿Vuepress為例來(lái)搞一下線上可以訪問的博客。
在開始實(shí)戰(zhàn)之前呢!透露一下最近在搞得開源庫(kù)Strve.js，它是一個(gè)可以將字符串轉(zhuǎn)換為視圖的JS庫(kù)，換句話講，也可以說是一款輕量的MVVM框架。目前Strve.js官方文檔就是用的基于Vuepress來(lái)進(jìn)行開發(fā)部署的，感興趣的可以訪問下方的官方文檔源碼地址，可以根據(jù)我的來(lái)進(jìn)行自定義配置自己的博客網(wǎng)站。如果覺得不錯(cuò)的話，別忘了幫忙點(diǎn)個(gè)Star啊!
Strve.js官方文檔源碼地址
- https://github.com/maomincoding/strvejs-doc
Strve.js官方文檔
- https://maomincoding.github.io/strvejs-doc/
實(shí)戰(zhàn)
自己親身實(shí)戰(zhàn)所攢下的經(jīng)驗(yàn)，請(qǐng)認(rèn)真往下看哦!
學(xué)習(xí)一個(gè)新技術(shù)，我們首先做得事就是打開官網(wǎng)文檔，根據(jù)快速上手或者指南來(lái)進(jìn)行大致的了解。
第一步
打開Vuepress官網(wǎng):
- https://vuepress.vuejs.org/zh/
官網(wǎng)上怎么安裝Vuepress項(xiàng)目已經(jīng)很詳細(xì)了，這里就不再闡述，可以根據(jù)快速上手快速搭建一個(gè)Vuepress項(xiàng)目。
- https://vuepress.vuejs.org/zh/guide/getting-started.html
一般搭建完成之后，會(huì)顯示以下目錄結(jié)構(gòu)：
- .
- ├── docs
- │ ├── .vuepress (可選的)
- │ │ ├── components (可選的)
- │ │ ├── theme (可選的)
- │ │ │ └── Layout.vue
- │ │ ├── public (可選的)
- │ │ ├── styles (可選的)
- │ │ │ ├── index.styl
- │ │ │ └── palette.styl
- │ │ ├── templates (可選的, 謹(jǐn)慎配置)
- │ │ │ ├── dev.html
- │ │ │ └── ssr.html
- │ │ ├── config.js (可選的)
- │ │ └── enhanceApp.js (可選的)
- │ │
- │ ├── README.md
- │ ├── guide
- │ │ └── README.md
- │ └── config.md
- │
- └── package.json
第二步
假設(shè)你已經(jīng)在第一步中成功搭建起了項(xiàng)目，并且成功啟動(dòng)。下面，我們將會(huì)改改代碼看下都是什么效果。
首先，我會(huì)看下這個(gè)文件doc > README.md，這個(gè)文件你可以把它理解成首頁(yè)。
- .
- ├─ docs
- │ ├─ README.md
以Strve.js文檔首頁(yè)為例：
- ---
- home: true
- heroImage: /logo.png
- heroText: Strve.js
- tagline: 一個(gè)可以將字符串轉(zhuǎn)換為視圖的JS庫(kù)
- actionText: 快速上手 →
- actionLink: /zh/started/
- features:
- - title: ⚡️ 快速地
- details: 超快的虛擬 DOM。
- - title: 📦 空間小
- details: 源代碼文件大小僅僅4kb。
- - title: 🗂 靈活地
- details: 易于靈活地拆裝不同的代碼塊。
- footer: MIT Licensed | Copyright © 2021-present maomincoding
- ---
上面的格式是Front Matter，可以根據(jù)官方文檔進(jìn)行詳細(xì)配置。
- https://vuepress.vuejs.org/zh/theme/default-theme-config.html#首頁(yè)
第三步
那么下面你需要關(guān)注的是Vuepress配置文件——config.js。
- .
- ├─ docs
- │ └─ .vuepress
- │ └─ config.js
同樣，拿Strve.js官網(wǎng)文檔為例：
- module.exports = {
- base: '/strvejs-doc/', // /site/strvejs/
- title: 'Strve.js',
- description: 'A JS library that can convert strings into view',
- head: [
- ['link', { rel: 'icon', href: '/logo.png' }],
- ],
- markdown: {
- lineNumbers: true
- },
- locales: {
- '/': {
- lang: 'en-US',
- title: 'Strve.js',
- description: 'A JS library that can convert strings into view'
- },
- '/zh/': {
- lang: 'zh-CN',
- title: 'Strve.js',
- description: '一個(gè)可以將字符串轉(zhuǎn)換為視圖的JS庫(kù)'
- }
- },
- themeConfig: {
- displayAllHeaders: true,
- sidebar: 'auto',
- sidebarDepth:4,
- nav: [
- { text: 'GitHub', link: 'https://github.com/maomincoding/strve' }
- ],
- locales: {
- '/': {
- selectText: 'Languages',
- label: 'English',
- ariaLabel: 'Languages',
- sidebar: [
- {
- title: 'Introduce',
- path: '/introduce/',
- },
- {
- title: 'Install',
- path: '/install/',
- },
- {
- title: 'Started',
- path: '/started/',
- },
- {
- title: 'Usage',
- path: '/usage/',
- },
- {
- title: 'Tool',
- path: '/tool/',
- },
- {
- title: 'Other',
- path: '/other/',
- }
- ],
- },
- '/zh/': {
- selectText: '選擇語(yǔ)言',
- label: '簡(jiǎn)體中文',
- sidebar: [
- {
- title: '介紹',
- path: '/zh/introduce/',
- },
- {
- title: '安裝',
- path: '/zh/install/',
- },
- {
- title: '快速上手',
- path: '/zh/started/',
- },
- {
- title: '使用',
- path: '/zh/usage/',
- },
- {
- title: '工具',
- path: '/zh/tool/',
- },
- {
- title: '其它',
- path: '/zh/other/',
- }
- ],
- }
- },
- smoothScroll: true
- }
- }
看到這些配置不要慌，都可以從官方文檔配置選項(xiàng)中可以找到。
- https://vuepress.vuejs.org/zh/config/
其次，需要重點(diǎn)說明的是我這里/和/zh是提供了多語(yǔ)言支持配置路徑，可以通過官方文檔的多語(yǔ)言支持選項(xiàng)進(jìn)行配置。
第四步
我之所以很簡(jiǎn)單地概括前面的步驟，是因?yàn)楣倬W(wǎng)文檔講解的比我更明白更詳細(xì)，我也不想浪費(fèi)大家的時(shí)間。
下面，我們就要開始部署。在部署打包之前呢!我們首先要注意的是配置文件，我們回到之前的配置文件。
我們需要注意的是base選項(xiàng)，
- module.exports = {
- base: '/strvejs-doc/',
- title: 'Strve.js',
- description: 'A JS library that can convert strings into view',
- head: [
- ['link', { rel: 'icon', href: '/logo.png' }],
- ]
- }
打開package.json文件。
- {
- "name": "strvejsdoc",
- "version": "1.0.0",
- "description": "Strve.js document address",
- "main": "index.js",
- "license": "MIT",
- "private": false,
- "scripts": {
- "dev": "vuepress dev docs",
- "build": "vuepress build docs"
- },
- "devDependencies": {
- "vuepress": "^1.8.2"
- }
- }
我們看到"scripts"屬性下有"build"指令。運(yùn)行打包即可。
打包后，默認(rèn)會(huì)打包到dist文件夾中，你可以把文件夾中的內(nèi)容放到線上網(wǎng)站上去，如果沒有網(wǎng)站，也沒有關(guān)系。本篇文章就是讓每個(gè)前端都擁有一個(gè)屬于自己的博客線上網(wǎng)站。
- .
- ├── docs
- │ ├── .vuepress
- │ │ ├── dist
第五步
我們會(huì)用到GitHub，所以需要?jiǎng)?chuàng)建一個(gè)倉(cāng)庫(kù)，名字可以起一個(gè)好記的。我這里因?yàn)槭且許trve.js為例，所以名為strvejs-doc。然后你需要做的是使用SSH方式Clone下來(lái)。
如果沒有配置SSH的可以根據(jù)我下面的步驟操作一下。
切換到 .ssh目錄
- cd ~/.ssh
瀏覽文件夾目錄
- ls
輸入你的郵箱(郵箱不必與GitHub賬號(hào)相同，個(gè)人郵箱即可)，然后一直回車
- ssh-keygen -t rsa -C "郵箱"
自動(dòng)啟動(dòng)
- eval "$(ssh-agent -s)"
添加文件
- ssh-add ~/.ssh/id_rsa
查看 id_rsa.pub 文件的內(nèi)容，復(fù)制一下，留存。
- cat id_rsa.pub
下面，我們就要打開Github，點(diǎn)擊右上角個(gè)人頭像下拉菜單中的Settings選項(xiàng)，然后點(diǎn)擊左邊欄的SSH and GPG keys選項(xiàng)。
點(diǎn)擊 New SSH key 按鈕。
輸入Title 下的內(nèi)容，這里隨便起一個(gè)好記的標(biāo)題。
然后輸入Key 下的內(nèi)容，把剛才保存的id_rsa.pub 文件的內(nèi)容復(fù)制到里面。
現(xiàn)在，大功告成!
以后，你只需要復(fù)制項(xiàng)目倉(cāng)庫(kù)中 Clone按鈕下的 SSH 選項(xiàng)框中的鏈接。
然后，Clone 這個(gè)鏈接即可。
Clone 下倉(cāng)庫(kù)之后，然后可以把剛才Vuepress項(xiàng)目導(dǎo)入進(jìn)去。
最后，Push一下。
第六步
首先，我們需要?jiǎng)?chuàng)建一個(gè)分支，比如命名pages。然后，打開GitHub遠(yuǎn)程倉(cāng)庫(kù)，點(diǎn)擊項(xiàng)目倉(cāng)庫(kù)Tab欄上的Settings選項(xiàng)，然后點(diǎn)擊Pages選項(xiàng)。
最后，在Source下選擇剛才創(chuàng)建的pages分支，然后選擇/(root)，點(diǎn)擊Save保存按鈕。
不出意外，上方會(huì)給出一個(gè)網(wǎng)址，這里我們先保存一下，待會(huì)配置完成我們?cè)冱c(diǎn)擊瀏覽網(wǎng)址。
第七步
在項(xiàng)目根目錄下創(chuàng)建一個(gè)deploy.sh文件，編輯如下內(nèi)容：
- #!/usr/bin/env sh
- set -e
- npm run build
- cd docs/.vuepress/dist
- git init
- git add -A
- git commit -m 'deploy'
- # 如果發(fā)布到 https://<USERNAME>.github.io/<REPO>
- git push -f git@github.com:<USERNAME>/<REPO>.git master:pages
- cd -
這里你需要自定義的是：USERNAME、REPO、master:pages，分別對(duì)應(yīng)用戶名、倉(cāng)庫(kù)名、(一般是master:分支名或者main:分支名)。
第八步
我們?cè)趐ackage.json文件中定義一個(gè)調(diào)試命令。
- "scripts": {
- "sh":"bash deploy.sh"
- }
然后運(yùn)行此命令。
最后，我們?cè)跒g覽器上打開剛才的網(wǎng)址。
以后，每次更改文檔，只需一條命令，即可更新線上網(wǎng)站。
結(jié)語(yǔ)
自動(dòng)化部署還有別的方案比如Github中的Actions，這里就不再詳細(xì)介紹了。趕快來(lái)試試上面的方案吧!部署一個(gè)屬于自己的博客。
