1024，快速打造你的文檔庫/靜態博客

時間 2019-11-16

原文原文鏈接

Create by jsliang on 2018-10-20 10:34:39
Recently revised in 2018-10-24 13:54:52html

Hello 小夥伴們，若是以爲本文還不錯，記得給個 star ，大家的 star 是我學習的動力！GitHub 地址前端

【2019-08-16】Hello 小夥伴們，因爲 jsliang 對文檔庫進行了重構，這篇文章的一些連接可能失效，而 jsliang 沒有精力維護掘金這邊的舊文章，對此深感抱歉。請須要獲取最新文章的小夥伴，點擊上面的 GitHub 地址，去文檔庫查看調整後的文章。vue

本文教你如何利用 GitHub 平臺搭建本身的博客/文檔庫。
若是，你的目的僅僅是想了解如何配置。那麼，你應該在看完 第三章基礎配置 後，就能夠本身去寫本身的博客/文檔庫，遇到不懂的問題，能夠本身翻閱 VuePress 文檔，解決你所須要解決的問題。
若是，你的目的是具體查找某組件：例如導航條、例如側邊欄的配置。那麼，你能夠直接查找目錄，跳到對應章節進行閱讀。node

參考文檔：webpack

參考地址：GitHub Pagesgit
參考地址：VuePress 中文網github

目前效果：web

一目錄

目錄名
一目錄
二前言
三基礎配置
3.1 搭建 GitHub Pages
3.2 搭建 VuePress
3.2.1 目錄講解
3.2.2 導航欄
3.2.3 側邊欄
3.2.4 默認首頁
四 VuePress 進階
4.1 修改樣式

二前言

返回目錄npm

通常的網站，大致由三部分組成：域名、服務器部署環境以及部署代碼。編程

GitHub Pages，由 GitHub 網站服務，爲衆多 GitHub 用戶提供了良好的服務器部署環境以及域名的好工具。【Github Pages 官網】
VuePress，是以 Vue 爲驅動的主題系統的簡約靜態網站生成工具 balabala……它是咱尤雨溪大神折騰出來的一個工具，初始目的是爲了方便他使用 Markdown 語法來寫文檔，而後生成 HTML 代碼，部署到服務器上便可。在衆多網友的修改下，它能夠拿來寫靜態網站，也就是能夠拿來發布咱們編寫的博文。【VuePress 官網】

說到這裏，小夥伴們大概懂了咱們要講什麼了~
可是，若是這只是一篇關於如何入門 GitHub Pages 和 VuePress 的文檔，我會以爲毫無心義。因此，jsliang 但願這篇文章可以整合網上的 GitHub Pages 和 VuePress 資料，而且比它們豐富一丟丟，加入 jsliang 使用心得，讓小夥伴們看完無需翻閱大量文章也能快速作好本身的我的文檔庫/博客。那樣，我就心滿意足了。由於……

不折騰的前端，跟鹹魚有什麼區別！

本文涉及的技術點：

GitHub
Git
Markdown

若是你不是很熟悉上面的技術，jsliang 推薦你去百度下資料，先學習下這些技術，再回來繼續學習。其中 GitHub 和 Git 的文章 jsliang 還沒有整理，小夥伴只能去百度獲取資料了，這裏我提供一篇本身寫的 Markdown文章：地址。
若是你熟悉且瞭解上面的技術，那麼，讓咱們愉快地繼續往下去折騰吧！

三基礎配置

3.1 搭建 GitHub Pages

返回目錄

新建倉庫( New repository )，在倉庫名( Repository name )中輸入 用戶名.github.io，例如個人就是：LiangJunrong.github.io，而後點擊 Create repository 便可建立一個部署好的環境。

Clone 項目至電腦，並新增 README.md 和 index.html：

README.md

Hello Github Pages
===

&emsp;這是個人 GitHub Pages 初始目錄
複製代碼

index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0,maximum-scale=1.0,user-scalable=no">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Hello Github Pages</title>
    <style>
        .container {
            margin-top: 300px;
            text-align: center;
        }
    </style>
</head>
<body>
    <h1 class="container">Hello Github Pages</h1>
</body>
</html>
複製代碼

上傳到 GitHub：

git add .
git commit -m "Github Pages"
git push
複製代碼

打開 用戶名.github.io：

如上，完成 GitHub Pages 的搭建，如今咱們已經擁有了一個免費部署靜態頁面的平臺了。那麼，下面咱們將講解如何經過 Markdown + VuePress 來編寫博客。

3.2 搭建 VuePress

返回目錄

安裝 VuePress

在你須要存放的目錄中，經過終端命令行安裝 VuePress：npm i vuepress -D

編輯 package.json：

package.json

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

注：

npm run dev 便可開始實時編輯模式
npm run build 便可對代碼進行壓縮打包，打包後的文件夾在 .vuepress/dist 上。

而後建立 docs 文件夾，並在 docs 文件夾下建立 README.md 文件

README.md

Hello VuePress
===
複製代碼

最後在終端執行命令 npm run dev，並打開 http://localhost:8080，獲得初步配置界面以下：

值得注意的是。在這裏，咱們是經過 npm run dev 即時獲取咱們修改的頁面顯示。
而後，咱們能夠經過 npm run build 打包咱們的代碼，你能夠在 .vuepress 中找到一個 dist 文件夾，而後將 dist 中的文件夾上傳至 用戶名.github.io，便可完成 VuePress 的部署。

3.2.1 目錄講解

返回目錄

在前面，咱們講解了如何設置 VuePress 並啓動如今，咱們來個基配的目錄，進行講解：

- docs                   - VuePress 存放目錄
 - .vuepress             - VuePress 配置目錄
  - public               - 共用文件存儲目錄
   - img                 - 共用圖片目錄
    - banner.png         - 圖片-首頁 banner
    - logo.ico           - 圖片-網站右上角小圖標
  - config.js            - VuePress 的 js 配置文件
 - listOne               - 側邊欄項目組1
  - pageOne.md           - 項目組1頁面1
  - README.md            - 項目組1默認頁面
 - listTwo               - 側邊欄項目組2
  - pageThree.md         - 項目組2頁面3
  - pageTwo.md           - 項目組2頁面2
  - README.md            - 項目組2默認頁面
 - README.md             - 網站默認首頁
+ node_modules           - node 依賴包
- package.json           - webpack 配置文件
複製代碼

其中，.vuepress 存放 VuePress 的配置目錄，public 中存放共有的文件，config.js 爲 VuePress 的配置文件，listOne、listTwo 是側邊欄組，對頁面進行個分類。

3.2.2 導航欄

返回目錄

在這裏，咱們開始進行頂部導航欄的配置。
首先，咱們填寫下 config.js 中的配置代碼：

config.js

module.exports = {
    // 左上角標題
    title: 'jsliang 的文檔庫',
    // 描述
    description: '前端工程師 jsliang 的文檔庫',
    // 頭部部署，右上角小圖標
    head: [
        // ico 配置
        ['link', {
            rel: 'icon',
            href: '/img/logo.ico'
        }]
    ],
    // 主題部署
    themeConfig: {
        /** 
         * 右側導航條
         * text - 顯示字段
         * link - 連接：注意先後帶 / 符號
         */
        nav: [
            {
                text: '主頁',
                link: '/'
            },
            /**
             * 多級菜單
             * 開頭 text 爲一級標題
             * 數組內 text 爲二級標題
             * link 爲連接，注意帶 /
             */
            {
                text: '博文',
                items: [
                    {
                        text: '微信小程序 bug 集中營',
                        link: 'https://github.com/LiangJunrong/document-library/blob/master/other-library/WeChatApplet/WeChatAppletBug.md'
                    },
                    {
                        text: '使用 GitHub Pages 和 VuePress 搭建網站',
                        link: 'https://github.com/LiangJunrong/document-library/blob/master/other-library/GithubPages/GithubPages.md'
                    }
                ]
            },
            {
                text: '關於',
                link: '/about/'
            },
            // 連接到網站
            {
                text: 'Github',
                link: 'https://www.github.com/LiangJunrong'
            },
        ]
    }
}
複製代碼

而後，啓動 npm run dev，打開 http://localhost:8080，你能夠看到導航欄部署完畢了。

3.2.3 側邊欄

返回目錄

VuePress 中的側邊欄配置，一共有三種方式：簡單配置，按組配置，分頁配置，有興趣的小夥伴能夠去：地址直接查看，這裏咱們單純講下咱們部署咱們的文檔庫用到的分頁配置。

目錄以下：

而後，咱們修改下 config.js：

config.js

module.exports = {
    title: 'jsliang 的文檔庫',
    description: '前端工程師 jsliang 的文檔庫',
    head: [
        // ...省略，配置代碼同 3.2.2    
    ],
    themeConfig: {

        nav: [
            // ...省略，配置代碼同 3.2.2   
        ],
        /**
         * 側邊欄配置：側邊欄組
         */
        sidebar: {
            // 側邊欄在 /index/ 目錄上
            '/index/': [
                ['', 'README'],
                ['indexTwo', '導航第二頁']
            ],
            // 側邊欄在 /about/ 目錄上
            '/about/': [
                ['', 'README'],
                ['GithubPages', 'GithubPages'],
                ['VuePress', 'VuePress']
            ]
        }
    }
}
複製代碼

最後，咱們運行 npm run dev，查看 http://localhost:8080 所示以下：

能夠看出，咱們已經成功配置了分頁形式的側邊欄。

3.2.4 默認首頁

返回目錄

VuePress 爲咱們設置了一套默認的首頁，咱們直接拿來用，看看它長什麼樣子吧！

首先，咱們找一張 banner.png 圖，放到 public/img/banner.png 上。
而後，咱們修改下 docs/README.md 文件：

docs/README.md

---
home: true
heroImage: ./img/banner.png
actionText: 皮皮蝦 咱們走 →
actionLink: /index/
features:
- title: 裝逼
  details: 在這裏，你能夠看到 jsliang 在這裏無限裝逼，因此你能夠盡情打臉。就算你懂，不要緊，打了臉再說~
- title: 搞笑
  details: 在這裏，你能夠得到各類學習歡樂，輕鬆進擊前端編程。點滴進步，成就不同的你。
- title: 深沉
  details: 在這裏，你能夠收穫一個廣州自身漂泊的人的情懷，感覺在這個煩躁的社會 jsliang 如何安身立命。
footer: jsliang 的文檔庫 | Copyright © 2018 不折騰的前端，和鹹魚有什麼區別
---
複製代碼

OK，因爲咱們從新修改了首頁（即 docs/README.md），因此咱們從新重啓下，Ctrl+C -> y -> npm run dev，從新打開 http://localhost:8080：