VuePress從零開始搭建本身的博客

VuePress從零開始搭建本身的博客

最近將本身的博客從Hexo轉移到VuePress中來，使用VuePress的過程當中也遇到了一些問題，寫一篇文章來記錄一下搭建過程和踩過的坑。

VuePress是什麼？

VuePress是以Vue驅動的靜態網站生成器，是一個由Vue、Vue Router和webpack驅動的單頁應用。在VuePress中，你可使用Markdown編寫文檔，而後生成網頁，每個由VuePress生成的頁面都帶有預渲染好的HTML，也所以具備很是好的加載性能和搜索引擎優化。同時，一旦頁面被加載，Vue將接管這些靜態內容，並將其轉換成一個完整的單頁應用，其餘的頁面則會只在用戶瀏覽到的時候才按需加載。

詳情請看VuePress官方文檔

VuePress特性

• 爲技術文檔而優化的內置Markdown拓展
• 在Markdown文件中使用Vue組件的能力
• Vue驅動的自定義主題系統
• 自動生成Service Worker(支持PWA)
• Google Analytics集成
• 基於Git的"最後更新時間"
• 多語言支持
• 響應式佈局

環境搭建

安裝

VuePress支持使用Yarn和npm來安裝，Node.js版本須要>=8才能夠。

全局安裝VuePress

yarn global add vuepress # 或者：npm install -g vuepress
複製代碼

建立項目目錄

mkdir project
cd project
複製代碼

初始化項目

yarn init -y # 或者 npm init -y
複製代碼

新建docs文件夾

docs文件夾做爲項目文檔根目錄，主要放置Markdown類型的文章和.vuepress文件夾。

mkdir docs
複製代碼

設置package.json

VuePress中有兩個命令，vuepress dev docs命令運行本地服務，經過訪問http://localhost:8080便可預覽網站，vuepress build docs命令用來生成靜態文件，默認狀況下，放置在docs/.vuepress/dist目錄中，固然你也能夠在docs/.vuepress/config.js中的dest字段來修改默認存放目錄。在這裏將兩個命令封裝成腳本的方式，直接使用npm run docs:dev和npm run docs:build便可。

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

建立.vuepress目錄

在docs目錄中，建立.vuepress目錄，.vuepress目錄主要用於存放VuePress相關的文件。

mkdir .vuepress
複製代碼

建立config.js

進入到.vuepress目錄中，而後建立config.js，config.js是VuePress必要的配置文件，它導出y一個javascript對象。

touch config.js
複製代碼

建立public文件夾

進入到.vuepress目錄中，而後建立public文件夾，此文件夾主要放靜態資源文件，例如favicons和 PWA的圖標。

mkdir public
複製代碼

此時，項目的結構差很少就出來了。

project
├─── docs
│   ├── README.md
│   └── .vuepress
│       ├── public
│       └── config.js
└── package.json

複製代碼

以上只是簡單了搭建了一下博客的開發環境，接下來是博客主要的基本配置config.js，也是必需要作的。

基本配置

一個config.js的主要配置包括網站的標題、描述等基本信息，以及主題的配置。這裏簡單的列舉一下經常使用配置。

網站信息

module.exports = {
    title: '我的主頁', 
    description: '姜帥傑的博客',
    head: [
        ['link', { rel: 'icon', href: '/img/logo.ico' }],
        ['link', { rel: 'manifest', href: '/manifest.json' }],
    ]
}
複製代碼

• title：網站標題
• description：網站描述
• head：額外的須要被注入到當前頁面的HTML"head"中的標籤，其中路徑的"/"就是public資源目錄。

具體配置詳情請看文檔：配置

主題配置

module.exports = {
       themeConfig: {
        nav: [
            { text: '主頁', link: '/' },
            { text: '博文',
              items: [
                { text: 'Android', link: '/android/' },
                { text: 'ios', link: '/ios/' },
                { text: 'Web', link: '/web/' }
              ] 
            },
            { text: '關於', link: '/about/' },
            { text: 'Github', link: 'https://www.github.com/codeteenager' },
        ],
        sidebar: {
            '/android/': [
                        "",
                        "android1", 
                    	 ...
                         ],
                "/ios/":[
                        "",
                        "ios1",
                        ],
                "/web/":[
                        "",
                        "web1",
                        ...
            				 ],
            },
        sidebarDepth: 2,
        lastUpdated: 'Last Updated', 
    },
}
複製代碼

• nav：導航欄配置，此配置主要用於配置導航欄的連接，例如以上主頁的link爲"/"，默認是根目錄下的README.md。"/android/"連接到根目錄docs下的android文件夾下的README.md文件。

• sidebar：側邊欄配置，你能夠省略.md拓展名，同時以/結尾的路徑將會被視爲 */README.md。'/android/'、'/ios/'和'/web/'是經過路由的方式將每一個頁面的標題抽取出來顯示。"/android/"是指根目錄下android文件夾中的路由，每一個路由連接都要有README.md。因此目錄結構以下：

  ├─── docs
  ├── README.md
  └── android
  │   └── README.md
  └── ios
     └── README.md
  
  複製代碼

• sidebarDepth：嵌套的標題連接深度，默認的深度爲1。

• lastUpdated：最後更新時間。

側邊欄如圖：

具體主題配置詳情請看文檔：主題配置

PWA配置

VuePress默認支持PWA配置的，須要在基本配置中開啓serviceWorker。

module.exports = {
	 serviceWorker: true,
}
複製代碼

而後再添加icons和Manifest配置，在public中添加manifest.json配置，和圖標。若是不知道PWA的能夠到PWA配置查看相關資料。

{
  "name": "姜帥傑",
  "short_name": "姜帥傑",
  "start_url": "index.html",
  "display": "standalone",
  "background_color": "#2196f3",
  "description": "姜帥傑的我的主頁",
  "theme_color": "blue",
  "icons": [
    {
      "src": "./logo.png",
      "sizes": "144x144",
      "type": "image/png"
    }
  ],
  "related_applications": [
    {
      "platform": "web"
    },
    {
      "platform": "play",
      "url": "https://play.google.com/store/apps/details?id=cheeaun.hackerweb"
    }
  ]
}
複製代碼

在config.js配置中添加manifest.json，因爲iphone11.3不支持manifest的圖標，因此加上apple-touch-icon圖標配置便可。

module.exports = {
	head: [
	        ['link', { rel: 'manifest', href: '/manifest.json' }],
	        ['link', { rel: 'apple-touch-icon', href: '/img/logo.png' }],
	      ]
}
複製代碼

最後在iphone中訪問網站，而後添加主屏幕便可。

自定義頁面

默認的主題提供了一個首頁（Homepage）的佈局(用於這個網站的主頁)。想要使用它，須要在你的根級 README.md的home: true，而後添加數據。

---
home: true
heroImage: /hero.png
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
---
複製代碼

效果以下：

若是你想自定義首頁或者其餘頁面，能夠在頁面的md文件中添加頁面Vue文件。Vue文件放置在docs/.vuepress/components目錄中。

---
layout: HomeLayout
---
複製代碼

例如我博客的自定義首頁：

部署上線

因爲構建的時候生成靜態頁面，因此將dist文件夾中的內容能夠部署在gitHub的pages或者coding的pages均可以。若是使用git上傳到github上，操做比較繁瑣，這裏使用腳本的方式自動部署到github上。

建立一個deploy.sh

在project下建立deploy.sh。

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上。

詳情請看，部署

示例：個人博客