如何利用GitHub搭建个人主页

zxl19 2020-05-05

如题，简单记录一下本博客的搭建过程。

搭建过程

选择博客模板

选择合适的博客模板可以实现更加复杂的博客功能并提高博客的美观性，具体可以在Jekyll Themes网站上进行选择。本博客使用FromEndWorld/LOFFER模板进行搭建，具体使用方式参考模板教程，在此向原作者表示感谢。完成此步骤之后，可以实现基本的博客功能。

选择开源协议

在仓库中新建LICENSE文件，GitHub会自动提示可供选择的开源协议，并提供说明以供参考。本博客模板使用MIT开源协议，MIT与BSD类似，但是比BSD协议更加宽松，是目前最少限制的协议，这个协议唯一的条件就是在修改后的代码或者发行包包含原作者的许可信息，适用于商业软件。2023年2月18日，本博客改为使用CC-BY-SA-4.0（知识共享-署名-相同方式共享-4.0版）开源协议，这是一种适用于非软件的开源协议。

设置赞赏按钮

在仓库中Settings->General->Features->Sponsorships，设置赞赏按钮，会在.github文件夹中生成FUNDING.yml文件，按照文件内的提示进行设置即可。如果不想注册相关网站可以上传微信赞赏码¹，在文件中添加微信赞赏码的链接来代替。

设置收藏夹图标

收藏夹图标（favicon）指的是在网页标签栏和书签中显示的小图标，使用图标生成器制作收藏夹图标²，在_config.yml文件中设置。

设置评论区组件

LOFFER模板自V0.5.0开始支持utterances评论区组件，安装这个GitHub App后可以将博客评论映射到仓库Issue。

脚本和配置选项说明，可以直接添加到博客模板中：

 <script src="https://utteranc.es/client.js"
         repo="zxl19/zxl19.github.io"            // 仓库名称
         issue-term="title"                      // Issue标题格式
         label="comment"                         // Issue标签
         theme="github-light"                    // 评论区主题
         crossorigin="anonymous"                 // 跨域设置
         async>
 </script>

在_config.yml文件中设置：

 utteranc:
     repo: zxl19/zxl19.github.io
     issue-term: title
     label: comment
     theme: github-light
     crossorigin: anonymous

utterance.html文件会读取_config.yml文件中的设置：

 <script src="https://utteranc.es/client.js"
         repo="zxl19/zxl19.github.io"
         // 博客模板在这里有笔误，应为site.utteranc.issue-term
         issue-term="title"
         label="comment"
         theme="github-light"
         crossorigin="anonymous"
         async>
 </script>

设置访问统计工具

使用RevolverMaps组件实时统计博客访问信息并进行可视化³，在更新显示样式时提供原脚本可以保留之前的统计结果。

<script type="text/javascript" src="//rf.revolvermaps.com/0/0/8.js?i=5qjglzc21e9&amp;m=0&amp;c=ff0000&amp;cr1=ffffff&amp;f=arial&amp;l=33" async="async"></script>

设置搜索引擎优化

搜索引擎优化（Search Engine Optimization，SEO）的目的是为了提高博客在搜索结果中的排名，在搜索引擎中搜索博客地址：

site:https://zxl19.github.io

如果搜索结果中包含博客内容，则说明博客已被搜索引擎收录。

设置自定义404页面

在404.md文件头部添加：

---
permalink: /404.html
---

Creating a custom 404 page for your GitHub Pages site-GitHub Docs

博客模板使用说明及格式约定

_posts文件夹中的每个.md文件对应一篇文章，文件名格式为year-month-day-url.md，以本文为例进行说明：
- year-month-day为文件创建日期，例如：2020-05-05；
- url为文章对应的二级域名，建议使用文章主题词，一般为两个单词，最多不超过三个单词，例如：blog-setup；
- 博客模板不会使用隐藏的.md文件生成网页，因此在文件名前加.可以将文件隐藏，进而将对应文章隐藏；

文章头部格式约定，以本文为例进行说明：

 ---
 layout: post
 title: 如何利用GitHub搭建个人主页
 date: 2020-05-05
 author: zxl19
 categories:
 tags: [Blog, GitHub, Note]
 comments: true
 toc: true
 pinned: false
 ---

layout：排版样式，文章为post，对应_layouts文件夹中的post.html文件；
title：博客中显示的标题；
date：博客中显示的日期：
- 博客模板根据此处的日期对于文章进行排序；
- 建议此处使用最近一次修改日期，文件名中使用创建日期；
- 为了避免文章顺序频繁变化，约定此处使用文件创建日期；
author：作者，多个作者使用英文逗号隔开，不需要使用中括号括起来；
categories：含义尚不明；

tags：标签；

按照字母顺序排列，数量上尽量精简；
多个标签使用英文逗号隔开，使用中括号括起来；

最后一个标签表示文章类型，目前分为以下三种：

标签	文章类型
`Archive`	资料存档，不定期更新
`Blog`	博客，与生活相关
`Note`	学习笔记，不定期更新

comments：是否开放评论，默认开放；
toc：是否生成目录，默认生成；
pinned：是否置顶，默认不置顶；
- 置顶文章会在博客首页顶端显示，应尽量减少置顶文章数量，使博客显示美观；
- 约定将所有需要置顶的文章链接按照时间顺序添加到2023-02-27-hall-of-fame.md文件中，只将这篇文章置顶；

文章正文格式约定：

为了防止自动截取摘要失败，约定在文章第一段后添加手动截取摘要的标记，将包含特殊符号、代码块、表格的部分放在标记之后；
为了文章显示美观，约定文章中不使用一级标题#，从二级标题##开始使用；

为了防止排版样式显示错误，在文章正文中避免使用|，约定使用汉字“ ”（音：滚）代替；

为了防止有序列表序号显示不连续，约定将代码段和表格缩进到有序列表中；

常见问题及解决方法

无法生成网站

仓库属性必须为Public，否则无法生成网站。如果仓库属性设置错误，需要修改仓库属性后git commit+git push一次才能恢复正常。

GitHub图片显示失败

修改hosts文件，具体参考CSDN博客进行解决；
科学上网；

在Gitee上同步博客

在Gitee上也可以搭建个人主页，可以保证访问速度和稳定性，具体参考B站视频。

曾尝试将本博客仓库托管到Gitee后同步搭建Gitee Pages，未成功。

另外一种简单的搭建教程

不使用博客模板新建仓库，搭建简单的GitHub Page，参考知乎回答，可以搭建一个简单的个人主页，可以作为项目介绍页或者简历使用，美观性较差，也难以实现更加复杂的功能。

博客模板更新同步

由于博客仓库通过博客模板构建，在博客模板更新后无法通过Pull Request的方式进行同步。为实现对于博客模板更新的同步，可以保留_posts文件夹下的文件，将其他文件直接替换为更新后博客模板中的文件，在进行简单配置后即可完成同步更新。

参考

以我的赞赏码为例。 ↩
以我的收藏夹图标为例。 ↩
以我的脚本为例，其中包含随机生成的唯一ID。 ↩