利用GitHub写博客的几种方式

rainzhaojy commented 7 years ago

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 commented 6 years ago

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

18wang commented 6 years ago

学习了

more-dopamine commented 6 years ago

涨姿势了。

xb21 commented 6 years ago

简书太丑了，issue走起来

HeminWon commented 6 years ago

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

shuideya commented 6 years ago

学习了

jun58 commented 6 years ago

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

coconilu commented 6 years ago

好东西，我决定使用issue

NaClYen commented 6 years ago

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

mask2012 commented 6 years ago

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

liub1934 commented 5 years ago

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

kdbreboot commented 5 years ago

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

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

weibin11 commented 4 years ago

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

google doc

frankcai4real commented 4 years ago

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

不过，可以查看历史版本

NaClYen commented 4 years ago

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

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

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

mvfki commented 4 years ago

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

Vincentzzg commented 4 years ago

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

mvfki commented 4 years ago

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

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

Vincentzzg commented 4 years ago

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

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

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

Yu4n commented 4 years ago

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

iScottMark commented 3 years ago

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

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

lelelongwang commented 3 years ago

用gist写博客更方便吧

zpengc commented 2 years ago

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

Lanbasara commented 2 years ago

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

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

zhangbw97 commented 2 years ago

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

magicsuu commented 1 year ago

cool

respectren commented 8 months ago

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

mvfki commented 8 months ago

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

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

respectren commented 8 months ago

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

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

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

wuyunfeng-Moving commented 1 week ago

非常感谢~实践搞起来~

rainzhaojy / blogs