利用GitHub写博客的几种方式

[rainzhaojy]

GitHub虽然不是一个传统的博客托管站点，但已成为程序员写博客的最爱，下面介绍几种在github上写博客的方法.

1. Github pages

github提供了pages功能, 分别是user pages和project pages, 区别如下:

	User Page	Project Page
是否多个	一个帐号只有一个	可以有多个, 每个repo都可以有对应的Project page
repo and branch	repo名必须为<username>.github.io, 页面在master上	repo名随意, 页面必须在分支gh-pages下
URL	http(s)://<username>.github.io	http(s)://<username>.github.io/<projectname>

举例 - 我的博客:

我使用github user page搭建了一个个人博客, 地址为 http://rainzhaojy.github.io, 对应的repo为 https://github.com/rainzhaojy/rainzhaojy.github.io . NOTE: 这个博客只是一个试验品, 新的博客都会使用github issues: https://github.com/rainzhaojy/blogs/issues

举例 - w3c:

W3C是一个使用github pages的一个很好的例子, w3c是github帐号名, 在user pages上定义了如何定义w3c spec, 即在repo "w3c.github.io" (对应的repo地址为 https://github.com/w3c/w3c.github.io ), 我们可以使用URL http://w3c.github.io 访问对应页面, 每一个spec都对应了一个project repo, 譬如webrtc, 文档定义在repo "webrtc-pc"的分支"gh-pages"下面, 对应的URL为 http://w3c.github.io/webrtc-pc

优点:

• 可以使用任意模版
• 是最正统的在github上写博客的方法

缺点:

• 需要自己定义模版 (也可以找别人现成的模版)
• 不能在线写博客, 需要在本地编写博客文件, 然后使用git命令提交到github
• 需要理解github pages, 需要懂git命令, 有一些门槛

总结:

• 这个方式适合对博客模版有要求, 了解git和github pages的人
• 因为有一点门槛, 适合爱折腾的程序员, 不适合普通人

2. 直接提交静态文件到github pages (Hexo等)

Github Pages其实等于jekyll engine + static web server, 方法1其实是利用jekyll搭建blog, 这两个功能都用到了.

我们也可以不使用jekyll engine, 只利用static web server这个功能, 也就是说, 直接上传静态站点文件html/css/javascript/image等等, 让Github Pages帮我们host这些静态页面.

Hexo + Github pages搭建blog其实就是只利用了github pages的static web server功能, hexo基于node.js, hexo在本机将用户的blog翻译成静态页面, 然后将这些静态页面上传到github上, 由github pages的static web server部署这些静态页面.

hexo与jekyll的主要区别是:

• md到html的转换时机不同, hexo在本机完成, jekyll是由github pages完成
• 提交到github库里的文件不同, hexo是提交转换后的静态页面, jekyll是提交转换前的md文件

我们可以使用hexo在本机写博客, 然后上传静态文件到github, 我们也可以使用其他模版引擎在本机写博客, 其实方法1里, 我们如果利用本机jekyll编译出静态文件, 然后只提交这些静态文件, 这样的做法和Hexo是一样的, 或者, 你也可以使用任何一种模版引擎 ( https://github.com/coffee-js/languages/wiki/static-blog-tools )来生成静态博客站点, 当然, 你也可以直接写html.

优点:

• 可以使用任意模版技术, 方法1其实是jekyll模版技术
• 可以使用任意模版
• 仍然是正统的在github上写博客的方法

缺点:

• 需要找到适合自己的模版技术, hexo是比较流行的一种
• 需要自己定义模版 (也可以找别人现成的模版)
• 需要在本地编写博客文件, 然后使用git命令提交到github
• 需要理解github pages, 需要懂git命令, 需要懂模版技术, 有一些门槛

总结:

• 这个方式适合对博客模版有要求, 了解模版技术, 了解git和github pages的人
• 有一点门槛, 适合爱折腾的程序员, 不适合普通人

3. 利用github issue写博客

利用github issues写博客也是一种做法. 我的博客: https://github.com/rainzhaojy/blogs/issues

优点:

• 简单方便
• 可以在线写, 可以预览, 可以评论, 可以加tag

缺点:

• 无法定制模版

总结:

• 如果你对github issues的格式能够接受, 那么这是最适合的方式
• 基本没有门槛, 适合绝大多数人, 推荐

4. 利用github wiki写博客

github wiki当然也可以写博客, github上每一个projec都有一个对应的wiki, 你可以在这里写博客, 譬如 https://github.com/coffee-js/languages/wiki

优点:

• 就是一个wiki系统，可以灵活的创建wiki page并相互link，也可以自定义右边的sidebar

缺点:

• 相比github issues，没有comments功能

5. 直接在repo里提交markdown文件

github建议每个项目都提供一个README.md文件, 在网页上浏览项目或子目录时, github会自动显示当前目录里的README.md文件, 利用这一功能, 也有人直接提交markdown文件, 譬如 https://github.com/kilimchoi/engineering-blogs, 这样也是一种方法, 只是打开你的blog时上面会先看到file list.

这样的做法其实就是把博客的md文件当成源代码一样提交到github里.

优点:

• 相比前面几种, 好像没什么独有的优点

缺点:

• 会看到文件列表, 格式比issues/wiki难看
• 需要懂git命令, 有一些门槛

总结:

• 既没有方法1, 2能够定制模版这样的优点, 又没有方法3, 4里可以在线编辑的优点, 因此不推荐这个方法

6. 项目文档的好选择

最近在为公司项目文档选型的时候发现一个不错的项目https://docusaurus.io/, 这是Facebook的开源项目，基于Nodejs，使用markdown，非常适合用于写项目文档，也可用于个人知识整理，相当于是wiki+blog系统，非常方便，样式也不错，和GA、搜索等也都集成的不错，也可以和GitHub Pages集成。拍乐云的项目文档就使用了这个，参考这里：https://developer.pano.video, Enjoy！

[aisnote]

用issue 不错，格式功能都够了

[18wang]

学习了

[more-dopamine]

涨姿势了。

[xb21]

简书太丑了，issue走起来

[HeminWon]

issues好像只能在线编辑，无法回滚历史版本也算缺点

[shuideya]

学习了

[jun58]

我是有个问题，假如issue写博客，一个issue很长，肯定是先在本地写好之后复制到issue上，然后自己本地的文件呢？有一定概率丢失，而且也不方便多地点编写（你在公司写了一点还没上传issue，之后你回家了，想继续写，但是文件都是公司的电脑上），我想知道你们都是这么做的，把文件存在什么地方。

[coconilu]

好东西，我决定使用issue

[NaClYen]

試用之後覺得很簡單且足夠使用! 感謝介紹!!

[mask2012]

issue真是脑洞大开，优点多多

[liub1934]

issue写博客美滋滋啊，满足日常使用，写的博客发布到其他平台如掘金 思否 CSDN等上面，除了手动复制外有啥偷懒快速的方法

[kdbreboot]

hi 我也想用issue写博客 基本的功能都操作一遍了 发现有两个缺点不知怎么解决 望指教～

comment的输入框太小了，如果是在线编辑 看不到正在输入文字的全貌
有什么软件可以推荐吗：本地编辑，实时预览，写好直接推倒想要的目录
怎么加目录？toc好像不好用？
望指教～

[weibin11]

我是有个问题，假如issue写博客，一个issue很长，肯定是先在本地写好之后复制到issue上，然后自己本地的文件呢？有一定概率丢失，而且也不方便多地点编写（你在公司写了一点还没上传issue，之后你回家了，想继续写，但是文件都是公司的电脑上），我想知道你们都是这么做的，把文件存在什么地方。

google doc

[frankcai4real]

issues好像只能在线编辑，无法回滚历史版本也算缺点

不过，可以查看历史版本

[NaClYen]

推薦各位可以搭配 https://hackmd.io/ 使用, 目前最愛的 markdown 編輯器!!

• 語法highlight
• 即時預覽(免切頁)
• 歷史版本
• 線上編輯

這幾個常見的需求都有喔~

[mvfki]

鬼才，自带markdown preview还附送评论区哈哈哈哈哈哈
不过我还是想要能自定义HTML的各种细节就是了

[Vincentzzg]

issue里面的文章竟然能直接Google搜索到 @rainzhaojy 博主有做什么特别的配置吗？

[mvfki]

issue里面的文章竟然能直接Google搜索到 @rainzhaojy 博主有做什么特别的配置吗？

Issue 本来就是可以被搜到的，所以说拿Issue写博客真的鬼才
我正在试这个人的说法，今天刚设置上暂时不知道有没有效

[Vincentzzg]

issue里面的文章竟然能直接Google搜索到 @rainzhaojy 博主有做什么特别的配置吗？

Issue 本来就是可以被搜到的，所以说拿Issue写博客真的鬼才
我正在试这个人的说法，今天刚设置上暂时不知道有没有效

也就是说issue里面的内容不用做为了让Google能搜索到去主动做一些标记验证的工作了。
哈哈，爱了，以后不用纠结在哪里记录分享知识了。

[Yu4n]

issue不支持latex格式，怎么输入公式呢

[iScottMark]

我是有个问题，假如issue写博客，一个issue很长，肯定是先在本地写好之后复制到issue上，然后自己本地的文件呢？有一定概率丢失，而且也不方便多地点编写（你在公司写了一点还没上传issue，之后你回家了，想继续写，但是文件都是公司的电脑上），我想知道你们都是这么做的，把文件存在什么地方。

这个方案应该是可行的：本地写好了，就 git push 到那个 issue 下的仓库代码里；相当于就利用 git 做版本控制，github 作为远程的云仓库，这样回家就可以直接 git pull 下来继续写作了，写完了再次 push 上去

[lelelongwang]

用gist写博客更方便吧

[zpengc]

但是issue写博客用到的图片还是需要上传到github仓库啊

[Lanbasara]

但是issue写博客用到的图片还是需要上传到github仓库啊

可以直接创建个新的仓库，既可以当做图床， 还可以搞个readme来做issue的目录，方便管理和归类。

[zhangbw97]

issue不支持latex格式，怎么输入公式呢
可以在https://latex.codecogs.com/里面写latex然后插入URL到markdown里面,这个帖子里有描述https://stackoverflow.com/questions/35498525/latex-rendering-in-readme-md-on-github

[magicsuu]

cool

[respectren]

issue写博客的话 搜索正文内容怎么搞？

[mvfki]

issue写博客的话 搜索正文内容怎么搞？

GitHub本就可以搜索嘛。滑到页面最上面，点进issue界面，上面有搜索框的。

[respectren]

issue写博客的话 搜索正文内容怎么搞？

GitHub本就可以搜索嘛。滑到页面最上面，点进issue界面，上面有搜索框的。

没错，就是不能像博客或者笔记那样，给出所有匹配的正文内容。

[wuyunfeng-Moving]

非常感谢实践搞起来