【效率工具】搭建自己的知识积累笔记本-Vuepress+GithubPages（一）

xn213
519 阅读9分钟

这是我参与更文挑战的第 11 天，活动详情查看： 更文挑战

前文介绍了 【效率工具】下一代前端数据模拟工具-mock service worker（一） 、【效率工具】Node+Koa-实现 mock 数据接口& mock.js 方案(二)-，-本文介绍搭建个人静态博客工具 Vuepress + github

仅当参考，按需食用，不足之处，欢迎各路大佬不吝赐教，补充完善，欢迎分享

  • 工欲善其事，必先利其器。实践（巧偷懒）促进科技发展-，-
  • 作为一个资深”搜集癖”，搜集整理的资料，文章越来越多，想着整理一个自己的笔记本，
  • 这篇文章和大家分享使用 Vuepress + github, 零成\本搭建自己的知识笔记本，助你增长知识，提高竞争力

Vuepress + Github Pages

基于 Vuepress 框架 和 GitHub Pages 功能，使用 Vue 语法开发 快速地搭建免费的 markdown 博客

Vuepress 简简介

github-stars--vuejs/vuepress: github-stars-vuejs-vuepress

Vuepress 是一个极简静态网站生成器, Vue 驱动的静态网站生成器

【文档】： Vuepress 文档 【源码】： github/vuejs/vuepress 【我的】： 余生的前端笔记本

【特点】：

  • 简洁至上 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。

  • Vue 驱动 享受 Vue + webpack 的开发体验，可以在 Markdown 中使用 Vue 组件，又可以使用 Vue 来开发自定义主题。

  • 高性能 VuePress 会为每个页面预渲染生成静态的 HTML，同时，每个页面被加载的时候，将作为 SPA 运行。

搭建过程

1. 创建项目目录

命令行使用命令创建进行：

mkdir fe-notes && cd fe-notes

2. 包管理初始化 && 安装依赖

# or use npm
yarn init # npm init
yarn add vuepress -D

3. 在 package.json 中添加一些 scripts， 方便项目运行

这时 VuePress 会在 http://localhost:8080 启动一个热重载的开发服务器， 不过还没有内容，

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

4. 添加博客内容

在项目根目录下，新建 docs 文件夹，并新建 markdown 文件，vuepress 会生成对应页面，即为博客文章

mkdir docs
# 新建一个页面 markdown
echo '# Hello VuePress!' > docs/README.md

5. 配置博客

然而如果没有任何配置，用户将无法在网站上自由导航。因此，为了更好地自定义我们的网站，我们接着在 docs 目录下新建 .vuepress 文件夹，执行命令如下：

# 新建 .vuepress 文件夹
mkdir docs\.vuepress

接着在 .vuepress 文件夹下新建 config.js 文件,这里的 config.js 便是一个 Vuepress 网站必要的配置文件，在其中添加如下代码：

module.exports = {
  base: '/blog-demo/',
  title: 'blog-demo',
  description: 'Vuepress blog demo'
}

其中配置项的含义为：

  • base：站点的基础路径，它的值应当总是以斜杠开始，并以斜杠结束。这里设置为 /blog-demo/ ，我们再次在本地运行项目，访问路径就需要变更为 http://localhost:8080/blog-demo/
  • title：网站的标题
  • description：网站的描述

默认主题配置

Vuepress 提供了一个默认主题，让我们不必自己去从零实现复杂的 markdown 文件渲染、目录结构等，直接按照规则去使用它即可。如果你想自定义自己的主题，请查看官方文档：Vuepress-开发主题。

首页

默认主题提供了一个首页的布局，想要使用它，需要在你的根级 README.md 以格式 YAML front matter 指定 home: true。因此，将我们最初创建的 README.md 修改一下：

---
home: true
heroImage: /vue-logo.png
heroText: blog-demo
tagline: 博客示例
actionText: 快速上手 →
actionLink: /
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
---
  • heroImage: 首页图片，图片放置在 .vupress/public 文件夹下，若没有该文件夹则自己创建一个，保存一张你想要的首页图片，并在此处引用。
  • 其它参数请参考官方文档：Vuepress-默认主题首页

导航栏

导航栏可能包含你的页面标题、搜索框、 导航栏链接、多语言切换、仓库链接，它们均取决于你的配置。在 .vupress/config.js 文件添加一些导航栏链接：

module.exports = {
    themeConfig: {
      // 你的GitHub仓库，请正确填写
      repo: 'https://github.com/xxxxxxx/blog-demo',
      // 自定义仓库链接文字。
      repoLabel: 'My GitHub',
      nav: [
        { text: 'Home', link: '/' },
        { text: 'FirstBlog', link: '/blog/FirstBlog.md' }
      ]
    }
}

接着，我们在 docs 目录下新建 blog 文件夹，在 blog 目录下创建 /blog/FirstBlog.md 作为我们第一篇博客的内容：

# 我的第一篇博客
My First Blog

我们再在项目根目录，即 blog-demo 下，输入命令 npm run docs:dev ，浏览器中访问 http://localhost:8080/blog-demo/ 查看页面效果，点击页面右上角的FirstBlog 可以看到我们第一篇博客：

本地效果预览

侧边栏

最后我们配置侧边栏，让用户体验更好一些，在 .vupress/config.js 文件添加一些代码：

module.exports = {
  themeConfig: {
    sidebar: [
      ['/', '首页'],
      ['/blog/FirstBlog.md', '我的第一篇博客']
    ]
  }
}

本地预览

至此我们已经完成了一个最简单的博客，再次运行项目，点击首页的按钮 快速上手 ，我们可以看到：

我的第一篇博客

在 VuePress 中注册组件

在 VuePress 中编写 Vue 代码，和我们通常的编写单文件的方式一致，有些时候我们有可能需要使用 Vue 的 UI 组件库。例如 Element，Mint 等，通常我们在项目中使用这些 UI 组件库的时候，我们都会在 main.js 或 botostrap.js 文件中统一注册。好在 VuePress 中也支持这种功能，我们可以通过创建一个 .vuepress/enhanceApp.js 文件来做一些应用级别的配置，这个文件 exprot default 一个钩子函数，在这个钩子中你可以做一些特殊处理，例如添加全局路由钩子，注册外部组件库。

// .vuepress/enhanceApp.js
// 全局注册 Element 组件库
import Vue from 'vue'
import Element from 'element-ui'
import 'element-ui/lib/theme-chalk/index.css'

export default ({
 Vue,
 options,
 router
}) => {
 Vue.use(Element)
}

在 Vue 正常开发中，有些时候我们可能会需要做一些自定义的组件，在 VuePress 中我们可以在.vuepress/components目录中编写我们的自定义组件，VuePress 在编译时遍历该目录中所有的 *.vue 文件，并见它们注册为全局组件。

// 注册一个自定义组件
// docs/.vuepress/components/hello.vue
<template>
 <div class="cpt-hello">Hello VuePress Demo</div>
</template>

这样我们在 Markdown 文件编写 Vue 代码的时候就不需要注册注册这些组件，边可以直接在 Markdown 中使用了。

// docs/.vuepress/vue/README.md
<template>
 <div class="test-demo">
  {{ msg }}
  <my-hello></my-hello>
  <el-button>button</el-button>
 </div>
</template>

<script>
export default {
 data () {
  return {
   msg: 'Hello VuePress!'
  }
 }
}
</script>

部署到 Github pages

当我们将文档写好后就到了我们最关心的地方了，怎么将打包后的代码推送到远程仓库的 gh-pages 分支上，网上应该有很多文章描述怎么做，但是很多方法比较麻烦，还好有工具 gh-pages 已经为我们解决了这个麻烦了。

# 1.下载 gh-pages 包
npm install -D gh-pages

# 2. 在 package.json 文件上添加脚本命令
"scripts": {
 "docs:dev": "vuepress dev docs",
 "docs:build": "vuepress build docs",
 // 上面我修改了 VuePress 的输出目录，所以您如果没有修改 .vuepress/config.js
 // 的 dest 属性，应该将这里的 dist 改为 .vuepress/dist
 "deploy": "gh-pages -d dist",
 "deploy:build": "npm run docs:build && gh-pages -d dist"
}

# 3. 打包并推送到 gh-pages 分支
// 注意: 使用配置了 远端仓库的 git 进行打包部署
//       使用cmd可能报错: Failed to get remote.origin.url (task must either be run in a git repository with a configured origin remote or must be configured with the "repo" option).

npm run deploy:build

// 4.打开你的 `Github pages`, 地址是 `https://<yourname>.github.io/<repo>`

xn213.github.io/fe-notes同与点击(余生的前端笔记本)

直接打开这里： 我的 config.js 配置, 及添加一键部署文件 deploy.sh

/**
 *
 * !!注意!! .sh 文件部署到 github 需要 git 已配置好 github 账号,
 *          且 git 已打开当前目录在当前目录下!
 */
module.exports = {
  title: '余生的前端笔记本', // 设置网站标题
  description: '记录着很多很正常很平凡的代码', // 描述 首页标题下方
  dest: './dist', // 设置输出目录
  base: '/fe-notes/',
  themeConfig: {
    // 假定 GitHub。也可以是一个完整的 Github 网址  // https://github.com/xn213/fe-notes
    repo: 'https://github.com/xn213/fe-notes',
    // 如果你的文档不在仓库的根部
    docsDir: 'fe-notes',
    // 可选，默认为 master
    docsBranch: 'gh-pages',
    // 默认为 true，设置为 false 来禁用
    editLinks: false,
    nav: [
      { text: '大前端', link: '/Frontend/' },
      { text: '笔记本', link: '/notes/' },
      { text: 'Vue', link: '/course/Vue/' },
      { text: 'React', link: '/course/React/' },
      { text: 'code工具', link: '/CodeTools/VSCode/VSCodeVue' },
      { text: '大杂烩', link: '/dzh/Explain' },
      { text: '余生博客', link: 'https://xn213.github.io/FrontEndNav/' },
      // { text: 'test', link: '/Test/' },
      // nav 下拉列表的配置
      // {
      //   text: '教程',
      //   items: [
      //     { text: 'Vue', link: '/course/Vue/VueRespond' },
      //     { text: 'React', link: '/course/React/' },
      //     { text: 'Vuepress', link: '/course/Vuepress/GithubPagesVuepressBlog' },
      //   ]
      // },
    ],
    sidebar: {
      '/Frontend/': [
        '/Frontend/代码可读性',
        '/Frontend/页面优化',
        '/Frontend/Fetch',
        {
          title: 'HTML', // 侧边栏组
          collapsable: true,
          children: ['/Frontend/HTML/HTML', '/Frontend/HTML/HTML5'],
        },
        {
          title: 'Css',
          collapsable: true,
          children: ['/Frontend/Css/The-Shapes-of-CSS', '/Frontend/Css/CssFonts_A-Z'],
        },
        {
          title: 'Js',
          collapsable: true,
          children: [
            '/Frontend/Js/this',
            '/Frontend/Js/EventLoop',
            '/Frontend/Js/prototype',
            '/Frontend/Js/WriteCode',
          ],
        },
      ],
    },
    sidebarDepth: 1, // sidebar目录 读取标题到 ##
  },
}

当然也可以新建文件deploy.sh 进行一键打包部署
//deploy.sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件/dist && 使用 gh-pages 部署到config.js中设置的对应仓库 gh-papes 分支下
npm run deploy:build

当然好用的博客搭建工具还有很多，这里列举部分工具，仅作参考，抛砖引玉，

可以定制自己的主题， 可以大大提高知识积累，有没有 get 到呢?

欢迎各路大神评论出你的私藏工具, 把你的 blog 分享给大家=，=

今日份预告 明天更新：

说完了 Vuepress + github 搭建自己的博客（知识积累笔记本）， 明天计划更新 探索其他搭建个人博客的工具： hugo && hexo...

赶快行动起来，大家自己的知识笔记本，记录学习，提升竞争力，下一篇敬请期待！ hahah~

可以参考学习的文章：

  1. 用 OpenWrite 配置博客导流公众号插件 - 公众号获取验证码阅读全文

  2. 使用 Github Actions 部署 VuePress 博客

avatar
文章
阅读
粉丝