GitHub Pages

GitHub Pages 概述

github提供的GitHub Pages服务使用户可以为项目提供漂亮的页面(即wiki),甚至可以利用github.io提供的二级域名实现自己的网站或博客。

GitHub Pages分为User, Organization Pages(博客或网站)和Project Pages(项目doc)。不过所有的页面必须的静态的,也就是说只能使用HTML/CSS/JavaScript等前端技术。但Github后台使用Jekyll^1将一些特殊格式的文本文档(Markdown ,Textile, Liquid)转化为html文档。所以我们可以使用Markdown等编辑器、提交markdown文档到github后,即可正常访问它生成的页面,通常提交之后要等上一会儿,10分钟以内。所以作为新手,可以现在本地搭建一个jekyll服务,实时查看更改。待熟悉之后,就可以使用程序员最喜欢方式写博客了,编辑,提交,编辑,提交…

创建User Pages

创建一个按照USERNAME.github.io命名的GitHub库,其中USERNAME为你的GitHub用户名。在该库的设置选项中点击GitHub Pages/Automatic Page Generator。按照向导编辑首页,选择网站模版。再查看该库的设置/GitHub Pages就可以看到Your site is published at http://johnnyfee.github.io的字样。这个就是我所用的github.io二级域名了。通过修改库中的内容,可以编辑我们的静态网站或博客。

创建Project Pages

创建方法类似于创建User Pages,只是git库是项目库。还有一个区别是,编辑网页的时候,需要切换到gh-pages分支,才能看到项目的文档。

Jekyll

[‘dʒekil; ‘dʒi:ki]

安装

See Running Jekyll on Windows – Madhur Ahuja.

  1. 安装Ruby2.0,傻瓜式安装即可。
  2. Download “DEVELOPMENT KIT” installer(http://rubyinstaller.org/downloads/)) that matches the Windows architecture and the Ruby version just installed.

    For example, DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe is for 64-bit Windows with Ruby 2.0.0 x64. Install the Ruby development kit from the same location above and extract it to path such as c:\devkit.

    Run the following commands

    ruby dk.rb init
    

    to generate the config.yml file to be used later in this Step. 如果生成的 config.xml 文件中包含了 - C:/Ruby200,则下一步可以省略。

  3. Edit the generated config.yml file to include installed Rubies. For example, in our case, it will look like this:

    - C:/Ruby200
    
  4. Run the following command to install to DevKit enhance your installed Rubies. This step installs (or updates) an operating_system.rb file into the relevant directory needed to implement a RubyGems

    ruby dk.rb install
    
  5. Install Jekyll using following command:

    $ gem install jekyll
    

    注意,对于中国大陆的用户请国内镜像:

  6. 使用Jekyll-Bootstrap快速搭建博客[^3]

    Jekyll-Bootstrap提供了能够被GitHub完美解析的文件结构和配置。

    git clone https://github.com/plusjade/jekyll-bootstrap.git USERNAME.github.com

    将修改push到远程库,等几分钟即可看到博客首页了,接下来就是慢慢完善你的博客了。

###显示页面中显示中文乱码[^4]

将%ruby installation path%/lib/ruby/gems/2.0.0/gems/jekyll-1.1.2/lib/jekyll/commands/以下文件中的File.read全部显示指定编码方式。

  • convertible.rb
  • tags/include.rb
  • commands/new.rb

如convertible.rb中的File.read调用方法修改为

self.content = File.read(File.join(base, name), :encoding => "utf-8")        

另外需要将文件保存为无BOM的UTF-8格式,通常通过编辑器(如Evernote)的另存为,便可看到BOM的勾选框。

###代码高亮[使用Pygments]

####安装python

Python Releases

添加安装目录到Path中。

笔者使用的版本为2.7.x,使用3.x会有问题。

####安装easy_install(即python的包管理器)

setuptools for Windows

下载ez_setup.py到pyton安装的根目录
运行该文件,将在相同目录下产生Scripts目录,在该目录中包含easy_install-3.3.exe和easy_install.exe,将该路径添加到Path中。

####安装Python Pygments

easy_install Pygments    

####设置代码高亮的样式

通过下面的命令可以查看当前支持的样式

>>> from pygments.styles import STYLE_MAP
>>> STYLE_MAP.keys()

Output:

['monokai', 'manni', 'rrt', 'perldoc', 'borland', 'colorful', 'default', 'murphy', 'vs', 'trac', 'tango', 'fruity', 'autumn', 'bw', 'emacs', 'vim', 'pastie', 'friendly', 'native']    

生成指定样式的css文件

pygmentize -S native -f html > pygments.css

将生成的css文件拷贝到主题的css目录下,如

%github pages project folder%\assets\themes\twitter\css\

引入default.html中引入css文件

// default目录如 %github pages project folder%\includes\themes\twitter\ // 引入如下代码

在文章中高亮代码
{% highlight java %} public class HelloWorld { public static void main(String args[]) { System.out.println("Hello World!"); } } {% endhighlight %}

运行jekyll服务,如果报以下问题

Liquid Exception: No such file or directory - /bin/sh in ...    

这个是语法高亮插件 Pygments 引起。解决方法是卸载最新版本的 Pygments (0.5.1+),重新安装 0.5.0 版本的 Pygments:

gem uninstall pygments.rb --version "=0.5.2"
gem install pygments.rb --version "=0.5.0"    

Windows 安装 Jekyll 若干问题的解决

####Python国内镜像

设置方法请参考 使用国内镜像源来加速

###代码高亮[使用Google Code Prettify]

###TOC

  • jekyll-table-of-contents
  • gfranko / jquery.tocify.js 建议使用,用于生成TOC。生成TOC没有问题,但是jquery.tocify.css中.tocify和bootstrap3的兼容不是很好。我使用以下代码覆盖其中的某些值:

    .tocify {
        position: inherit;
        width:240px;
        max-height: 80%;
        overflow: auto;
    }
    

    然后,使用bbarakaci / fixto将toc元素的定位变成fixed。同时,加入以下class调整样式以适应自己的页面:

    #toc {
            margin: 20px 0px 20px 0px;
    }
    
    .active {
        color:white;
        background-color: #dff0d8;
    }
    

###分页

Pagination

###分享

####分享到

####划词分享

###关注

###评论

在_includes/custom下添加文件duoshuo,内容为从duoshuo.com获取到的代码,以下代码把short_name的值改为jekyll _config.yml中配置的值,故以下代码通用。

其中 short_name的值在_config.yml中配置,之后会提到。

修改‘_includes/JB/’下的comments文件,添加以下分支

{{ '{% when "duoshuo"' }}%}
{{'{% include custom/duoshuo' }}%}

###关联

####关联推荐
在_includes/themes/[theme-name]/post.html的末尾添加通过安装关联推荐插件中的两段代码,注意两段脚本的顺序要一致。

//第一段 // 第二段

####TOP

通过无觅的热门文章Widget获得代码,复制到你需要热门文章的地方。

###分类

###全文搜索

###统计

###Read More

###Jekyll常用命令

####本地运行服务

jekyll serve --watch

通过watch参数可以让jekyll服务自动感知更改。其他用法请参考Basic Usage

####创建文章

$ rake post title="Hello World"

####创建页面

$ rake page name="about.md"

#Create a nested page:

$ rake page name="pages/about.md"

#Create a page with a “pretty” path:
$ rake page name="pages/about"
# this will create the file: ./pages/about/index.html

其他主题请参考Jekyll和Jekyll-BootStrap的官方文档,相关链接见参考

###主题参考

##GitHub的Markdown解析器

  • ****加粗标签之间不能有空格,否则启动本地服务时解析失败,在GitHub的Markdown解析器上能否通过为验证。

##Jekyll-AJAX

##liquid

##加速

另外,七牛云存储也可以托管静态文件,速度会明显比访问github快,所以不妨试试,以下是两个参考教程:

至少你可以考虑将图片放到七牛上去,在文章中使用网络地址插入图片,方便预览,也加速图片的加载。

##其他

##参考

[^3]: Zero to Hosted Jekyll Blog in 3 Minutes