当前位置: 首页 > 工具软件 > md-pages > 使用案例 >

如何搭建自己的github-pages个人博客

阎璞瑜
2023-12-01

相信大家都曾想过做一个自己的博客网站,上传一些自己的博文、作品等等,尤其是技术开发人员,就更想有一个属于自己的小天地了。但以往搭建博客网站的方案通常需要买云服务器、买域名等等,非常麻烦。对于需求不高,只想搭建一个静态网站的人来说,那些方案过于繁琐也没有时间维护。

本文推荐的一个方案是,基于Github,建立一个自己的github静态网站,过程非常简单,只需要你申请一个github账号(相信开发人员一般是会有的,没有的话,直接去https://github.com注册一个)

搭建github pages个人网站,主要分为以下几步:

1、拥有一个github账号,了解github的基本操作及git分支的概念

此部分对开发人员应该不陌生,如果不甚了解,可参考文章快速了解github基础信息:https://www.jianshu.com/p/f82c76b90336

2、注册申请gitlab.io仓库

简单来说,和普通创建仓库一样,创建一个命名为 username.github.io 的仓库,如我的github账号是Liusq-Cindy,仓库命名为Liusq-Cindy.github.io,系统会自动将其作为你的github pages仓库的(创建仓库可参考官方教程—如何创建一个github仓库)。

此部分不做赘述,官网说的非常清楚,可参考:github pages 官网

由此,其实你的个人网站已经搭建好了,地址应该如:https://liusq-cindy.github.io,该网站所承载的资源就是你在github page中所上传的内容。此时应该页面只有一句Hello Word,因此下面尝试创建一个简单的页面架构。

3、最基础的网站框架——关于jelly模板

现在你拥有了一个仓库和对应的博客网址,所需的只是把你需要的文件拷贝到你的库里。如果需要快速搭建一个基础的博客网站,Gihub官方提供了一个博客生成工具 Jekyll(中文官网英文官网)、此外,也有很多人会使用 Hexo 博客框架 来生成博客,这两者都支持Markdown,而且可以一键部署等等,对于需要快速构建博客的人群或者非技术开发人员非常友好,且有很多的模板和主题可供使用,能节省大量的时间。

关于以上工具的使用,可直接参考官方文档,描述的很详细。如果是技术开发人员,对html/css/javascript及git、打包比较了解,也可以自己手动构建网站。

以下介绍自己手动基于Vue搭建应用

4、基于vue搭建github-pages个人网站

作为前端开发人员,vue的开发应该是非常熟悉的,但是在搭建github-pages个人网站的过程中,还是遇到了一些问题,下面会将整体的流程和遇到问题的解决方案总结如下:

1、第一步,先在仓库内创建一个空的vue应用

创建一个vue-cli应用可直接使用命令行创建,也可以从现有的空的vue仓库中fork一个

// 在全局安装了node、webpack、vue-cli之后
vue create 项目名
// 然后按照提示输入

2、第二步,处理md文件

如果想要在个人网站中上传博文,保证其格式的美化,必然需要支持一下markdown,否则手写标签效率太低。网上关于 [ vue解析md文件 ] 有很多的解决办法,但大多会有一些bug存在(如代码无法高亮等),以下为亲测可行的md文件处理的解决方案

(1)安装以下npm依赖包:

markdown插件—解析md文件

npm i vue-markdown-loader@0 -D

markdown样式表—-对应的markdown转换成html的样式

npm install --save github-markdown-css

代码高亮及行号的依赖—-处理代码高亮及行号

npm install --save highlightjs-line-numbers.js

(2)修改webpack基础配置

在 build / webpack.base.config.js 文件, module: { rules: [] }中添加:

{
      test: /\.md$/,
      loader: 'vue-markdown-loader',
      options: {
        preprocess: function (MarkdownIt, Source) {
          MarkdownIt.renderer.rules.table_open = function () {
            return '<div class="table-container"><table class="table">';
          };
          MarkdownIt.renderer.rules.table_close = function () {
            return '</table></div>';
          };
          return Source;
        }
      }
    }

即表示将匹配到的.md文件通过vue-markdown-loader插件解析.

(3)在需要引入md文件的页面首页组件内引入github-markdown-css的样式插件及高亮插件,可以是App.vue,我这里是src/components/posts目录下的index.vue

import 'highlight.js/styles/github.css'
import 'github-markdown-css'

注:将需要匹配到该样式的组件添加class="markdown-body"以匹配样式表

(4)根目录下index.html文件中引入srcipt文件及css样式,且需要手动调整一下highlightjs-line-number.js的样式,index.html文件内容如下:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <title>liusq</title>
    <link
      href="https://cdn.bootcss.com/highlight.js/9.6.0/styles/atelier-lakeside-dark.min.css"
      rel="stylesheet"
    />
    <script src="//cdn.bootcss.com/highlight.js/9.11.0/highlight.min.js"></script>
    <script>
      hljs.initHighlightingOnLoad();
    </script>
    <script src="//cdn.bootcss.com/highlightjs-line-numbers.js/1.1.0/highlightjs-line-numbers.min.js"></script>
    <script>
      hljs.initLineNumbersOnLoad();
    </script>
    <script
      src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-MML-AM_CHTML"
      type="text/javascript"
    ></script>
  </head>
  <body>
    <div id="app"></div>
    <!-- built files will be auto injected -->
  </body>
</html>
<style>
  .hljs-line-numbers {
    text-align: right;
    border-right: 1px solid #ccc !important;
    margin-right: 10px !important;
    padding-right: 5px !important;
    color: #999;
    -webkit-touch-callout: none;
    -webkit-user-select: none;
    -khtml-user-select: none;
    -moz-user-select: none;
    -ms-user-select: none;
    user-select: none;
  }
</style>

(5)最后,页面引入md文件如下:

<template>
  <div class="hello markdown-body">
    <Readme></Readme>
  </div>
</template>

<script>

import 'highlight.js/styles/github.css'
import 'github-markdown-css'
import Readme from './test.md'// 引入md文件

export default {
  name: 'HelloWorld',
  components: {
    Readme
  }
}
</script>

可根据需要灵活变动组件位置及引入markdown样式的位置。

【参考文章:vue解析markdown文件并展示

3、第三步,打包vue文件

注意对于github-pages个人博客,仓库上传的文件不能直接将vue项目上传,是需要将项目进行打包编译的。

一般对于vue项目,打包使用 npm run build,webpack会将项目打包,打包文件会生成在dist目录下,将dist目录内容上传到github-pages仓库对应master分支上即可,但打包也可能会遇到一些问题。

打包后项目资源无法加载?点击index.html空白

出现这种情况,可打开控制台看看,index.html中是否没有加载任何css、js文件,如果是,多半是我们再config中的路径配置没有改过来,加载不到文件,打开项目根目录config下的index.js文件,进行如下修改:

assetsPublicPath: ‘/’ 改为 assetsPublicPath: './'

对于字体图标无法加载,修改build/utils.js文件,修改publicPath:’’…/…/"

if (options.extract) {
      return ExtractTextPlugin.extract({
        use: loaders,
        publicPath: '../../',
        fallback: 'vue-style-loader'
      })
    } else {
      return ['vue-style-loader'].concat(loaders)
    }

保存后重新打包。

【参考文章:vue打包问题

4、第四步,多分支管理

由于github-pages默认会加载master上的代码,所以master上的代码需要是打包后的dist文件内容,那么对于日常开发所需,我们需要另一个分支来存储所有的代码。(说是可以设置gh-pages为仓库的加载分支,但是我在新版github官网中仓库的setting,没找到这个source设置的修改,如果有人知道,请火速联系我)

对于gh-pages打包后,要将dist目录拷贝到指定的分支,如master上,除了手动操作,也可以使用如下命令:( git subtree push --prefix docpath origin branch ),此处应该是

git subtree push --prefix dist origin master

由此,存在两个分支,master专门存打包后的内容,gh-pages存的是所有代码。

后续则是对网站的优化及拓展了,和其他vue项目无异,此处不再赘述

 类似资料: