学习Github page写博客

发表于 | 分类于

Github可以建立个人静态网页，虽然只能写写博客，但省去了搭服务器、申请公网ip、买域名等复杂的步骤。

Github page和Jekyll介绍

Github page建立个人主页

操作也很简单，官方教程说得很清楚

  1. 创建一个公库，叫做USERNAME.github.io，这里的USERNAME是你的github账户名
  2. 在库的setting里选择一个theme，也可以用其它的Jekyll theme，我这里用的就是一个叫NexT的第三方主题
  3. 按照主题教程修改_config.yml和index.md两个文件即可编辑网页风格和主页内容
  4. 已经可以了，在浏览器中输入USERNAME.github.io，就能打开你的主页了，每次修改后大概要等1-2分钟才会完成网页同步

每个仓库可以有一个Github page

（to.be.continue）

Jekyll

这是一个从markdown等文本文件生成静态网页的网页编译器，是基于ruby语言的，可以在本机装一个Jekyll，然后编译网页，host一个自己的服务器。但我没装，Github会自动编译USERNAME.github.io这个库里面的文件，然后更新到对应的个人主页上。

Jekyll拥有各种各样的theme，github原生支持不到10种，功能都非常简单，也比较丑，建议使用第三方的主题。我这个站使用的是NexT。实验室建站可以考虑使用YosefLab的同款模板

自动生成静态网站的工具还有Hexo和Hugo等，详见Jekyll / Hugo / Hexo 比较。但我认为用Jekyll的主要好处是github支持直接托管网站，这样一方面不需要自己维护服务器，另一方面，其他人是怎么写博客的，源码你都能在对应的github repo里看到，省去很多学习成本。

撰写博客

最详细的教程当然是Jekyll官方文档，这里只记录一些很重要的，以及文档里没有的知识点。

博客文章规范

文章用markdown写，也支持一些其它格式，文件要放在_post文件夹下，命名要符合下面的规范

1
2
年-月-日-标题.md
如 2011-12-31-new-years-eve-is-awesome.md

md文件开头要有一段yml信息，对于博客文章而言大概是这样

1
2
3
4
5
6
---
title: 学习Github page写博客
date: 2022-06-03 15:20:00 +0800
categories: blogs
tags: [Github, jekyll]
---

date的+0800表示时区在东八区，不能省略，如果时间设定成未来时间，Jekyll在编译时会跳过这篇文章，详情见使用Jekyll时遇到的时区问题。

头文件后，用markdown语言编写即可，markdown的编辑器有很多，推荐使用vscode，详细教程

缩略展示

  1. 在_config.yml文件里，设置excerpt_separator: <!-- more -->
  2. 在文章中想要截断的地方加上<!-- more -->，则从主页看到的文章会显示这段之前的文字，展开阅读下文

代码高亮

markdown的代码是用`键，即~下面的那个，把代码框起来，多行的话则是用三个`前后框住，在前面三个撇之后声明使用的语言就可以按照该语言的格式高亮。

支持语言和对应声明方式一览

1
2
3
4
5
6
7
8
9
```ruby
def show
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end
```

（btw，上面这段是通过在每行代码前面加上四个空格打出来的，在markdown里这叫做“代码围栏”） 显示效果如下

1
2
3
4
5
6
7
def show
  @widget = Widget(params[:id])
  respond_to do |format|
    format.html # show.html.erb
    format.json { render json: @widget }
  end
end

Jekyll支持另一种高亮方法，在正常的markdown预览器中无法显示，但编译成网页后显示正常，而且可以切换高亮风格(不过我觉得原生的很够用了)

img

 def foo puts 'foo' end 
1

 def foo puts 'foo' end

插入图片

和markdown一样，Jekyll是可以插入网络图片的

1
2
![图片名](图片链接)
如 ![img](https://markdown.com.cn/assets/img/philly-magic-garden.9c0b4415.jpg)

img

如果要插入自己的图片，就把图片上传到博客repo根目录的/assets文件夹里，再用相对目录索引

1
![img](/assets/images/2022-06-03-github-page-first-step.md/shiprock.c3b9a023.jpg)

img

插入视频、pdf、html文件

这些都是通过在markdown中插入html代码实现的，最重要的是<iframe>这个组件，它可以插入各种各样的东西。

<iframe>插入的内容很多在vs-code的markdown预览器上无法正常显示，但push到github后，主页上就能显示了，暂时还不知道为什么。

插入视频

插入bilibili视频

参考网页

先获取视频的cid和aid，在下面的代码中修改这两项，再把修改后的html代码加到md文件中想要视频出现的地方即可

1
2
3
<div style="position: relative; padding: 30% 45%;">
<iframe style="position: absolute; width: 100%; height: 100%; left: 0; top: 0;" src="https://player.bilibili.com/player.html?cid=731300778&aid=726930359&page=1&as_wide=1&high_quality=1&danmaku=1" frameborder="no" scrolling="no" allowfullscreen="true"></iframe>
</div>

插入youtube视频

直接在youtube页面点击分享 -> 嵌入，复制那段<iframe开头的html代码，放到md文件里就行

插入微博视频

1
2
3
<div style="position: relative; padding: 30% 45%;">
<video style="position: absolute; width: 100%; height: 100%; left: 0; top: 0;" controls="controls" src="https://f.video.weibocdn.com/o0/WqIEQCkLlx07WDlN7REY01041200pOlh0E010.mp4?label=mp4_1080p&template=1080x1920.24.0&media_id=4777383199440919&tp=8x8A3El:YTkl0eM8&us=0&ori=1&bf=4&ot=v&ps=3lckmu&uid=2tKINp&ab=7397-g1,6377-g0,1192-g0,3601-g29,1258-g0,7598-g0&Expires=1654505112&ssig=m3Yf2IsS57&KID=unistore,video"></video>
</div>

src换成微博视频右键点击“复制链接地址”得到的链接

插入pdf、html文件

把上面某段iframe中的src改成文件路径即可

1
2
3
<div style="position: relative; padding: 30% 45%;">
<iframe style="position: absolute; width: 100%; height: 100%; left: 0; top: 0;" src="/assets/images/2022-06-03-github-page-first-step.md/NIPS-2016-dual-learning-for-machine-translation-Paper.pdf" frameborder="no" scrolling="no" allowfullscreen="true"></iframe>
</div>

插入思维导图（mindmap）

markdown的多级标题天然地很适合思维导图，这里可以用一个markmap插件去做自动转换。有两种用法，可以在线转换并导出成html或svg文件，又或者可以安装它的vs-code插件。打开mindmap预览并export html。然后用插入html的方法将其放到文章里。建议稍微调整一下padding，让导图面积大一点，同时为了不影响排版，做一个隐藏点击展开。

1
2
3
4
5
6
<details>
  <summary><b style='color:#FF7F7F;'>Click to view mindmap!</b></summary>
<div style="position: relative; padding: 100% 100%; background: #D3D3D3;">
<iframe style="position: absolute; width: 100%; height: 100%; left: 0; top: 0;" src="/assets/images/2022-06-03-github-page-first-step.md/mm.html" frameborder="no" scrolling="no" allowfullscreen="true"></iframe>
</div>
</details>
Click to view mindmap!

这个页面中的思维导图始终调不成满意的样式，还是单独搞一个html页面更好看一点

1
[<b style='color:#FF7F7F;'>Click to view mindmap in a new tab!</b>](/assets/images/2022-06-03-github-page-first-step.md/mm.html){:target="_blank"}

Click to view mindmap in a new tab!

评论功能

这里建议使用gitalk，因为其它支持的要么停止服务了，要么被墙。gitalk本质上是在github.io这个repo里提issue，所以只要网页能访问，评论就能打开。

  1. 进入github -> Settings -> Developer settings -> OAuth Apps -> New OAuth App，或者直接点这里
  2. 填上面网页里的表，除了Authorization callback URL一定要填USERNAME.github.io，其它都随便填
  3. 按Register application按钮，得到Client ID和Client Secret.
  4. _config.yml里，按照刚才得到的信息和你的个人信息填写如下内容： 
    1
    2
    3
    4
    5
    6
    7
     gitalk:
   enable: true
   clientID: Client ID
   clientSecret: Client Secret
   repo: USERNAME.github.io
   owner: USERNAME
   admin: [USERNAME]
  5. 把_includes/comments/gitalk.html的内容用这个文件里的内容替换。这是为了避免文章名太长导致的报错，详情见这里
  6. 可以了，每篇文章需要作者开一个Issue，然后其他人才可以评论（在admin里的人就可以开Issue）。也不用特地去开，上传一篇博客之后，拉到最底下第一次加载评论区的时候就自动有一个新Issue了