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：

完美！这样，咱们就完成了基础的配置了！！！

四 VuePress 进阶

4.1 修改样式

返回目录

正在逐步完善。

若是你以为该篇文章对你很是有用，请给我在 GitHub 上的文档库一个 star，你的 star 是我不断折腾的动力~ 【Github 地址】

jsliang 的文档库由梁峻荣采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。
基于github.com/LiangJunron…上的做品创做。
本许可协议受权以外的使用权限能够从 creativecommons.org/licenses/by… 处得到。