為什麼選用VuePress:它是vue的一個子項目,學過vue的小夥伴可快速上手,此外它的極簡風格也很讓人喜歡,但是也可以安裝各種主題,甚至自定義主題
它可以直接将我們寫的markdown檔案直接轉成html
為什麼選用gitee托管,gitee、github都有這樣的服務,是免費的,選gitee是因為快,github可能通路速度很慢
vue.js的官網就是用vuepress搭建的 https://cn.vuejs.org/
vuepress的官網 https://vuepress.vuejs.org/zh/
快速上手
前提條件
VuePress 需要 Node.js (opens new window)>= 8.6
本文會幫助你從頭搭建一個簡單的 VuePress 文檔。如果你想在一個現有項目中使用 VuePress 管理文檔,從步驟 3 開始。
1、建立并進入一個新目錄
mkdir vuepress-starter && cd vuepress-starter
2、使用你喜歡的包管理器進行初始化
3、将 VuePress 安裝為本地依賴
不推薦全局安裝 VuePress
4、建立你的第一篇文檔
mkdir docs && echo '# Hello VuePress' > docs/README.md
5、在 package.json 中添加一些 scripts(opens new window)
這一步驟是可選的,但我們推薦你完成它。在下文中,我們會預設這些 scripts 已經被添加。
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
6、在本地啟動伺服器
VuePress 會在 http://localhost:8080 (opens new window)啟動一個熱重載的開發伺服器。
通路效果如下:
目錄結構
.
├── 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: 用戶端應用的增強。
一個 VuePress 網站必要的配置檔案是
.vuepress/config.js
module.exports = {
title: 'Hello VuePress',
description: 'Just playing around'
}
首頁
預設的主題提供了一個首頁(Homepage)的布局 (用于 這個網站的首頁)。想要使用它,需要在你的根級 README.md 的 YAML front matter 指定 home: true。以下是一個如何使用的例子:
---
home: true
heroImage: /hero.png
heroText: Hero 标題
tagline: Hero 副标題
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
---
你可以将相應的内容設定為 null 來禁用标題和副标題。
任何 YAML front matter 之後額外的内容将會以普通的 markdown 被渲染,并插入到 features 的後面。
導航欄 Logo
你可以通過 themeConfig.logo 增加導航欄 Logo ,Logo 可以被放置在公共檔案目錄:
// .vuepress/config.js
module.exports = {
themeConfig: {
logo: '/assets/img/logo.png',
}
}
導航欄連結
你可以通過 themeConfig.nav 增加一些導航欄連結:
// .vuepress/config.js
module.exports = {
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: 'External', link: 'https://google.com' },
]
}
}
側邊欄
想要使 側邊欄(Sidebar)生效,需要配置 themeConfig.sidebar,基本的配置,需要一個包含了多個連結的數組:
// .vuepress/config.js
module.exports = {
themeConfig: {
sidebar: [
'/',
'/page-a',
['/page-b', 'Explicit link text']
]
}
}
更多配置可參考官網,官網講的還是比較詳細的
https://vuepress.vuejs.org/zh/theme/default-theme-config.html#%E9%A6%96%E9%A1%B5
部署
在giee建立個一個倉庫
開通 Gitee Pages服務(首次開通可能需要實名注冊,嫌麻煩的話可以選用 Github)
啟動後會自動生成一個位址:http://xxx.gitee.io/你的倉庫名/
在項目根目錄下建立
deploy.sh
#!/usr/bin/env sh
# 確定腳本抛出遇到的錯誤
set -e
# 生成靜态檔案
npm run 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 [email protected]:<USERNAME>/<USERNAME>.github.io.git master
# 如果釋出到 https://<USERNAME>.github.io/<REPO>
# git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages
# 這裡的位址就放剛剛建立的倉庫位址就好
git push -f [email protected]:xxx/myblog.git master
cd -
然後在package.json中添加
"scripts": {
"deploy": "bash deploy.sh",
},
注意: 這裡如果直接用cmd去跑
npm run deploy
的話會報錯
因為 bash 是linux下的指令
解決辦法:
我們一般都有git環境,可以用
這時我們會發現在
docs\.vuepress\dist
下生成了對應的靜态頁面
打開 http://su_shuwang.gitee.io/myblog/即可看到我們部署成功後的部落格啦
後續搭建内容會持續更新。。。