內容目录

上一个主题

3.4. 版本库钩子扩展

下一个主题

4. 工作协同

本页

3.5. 建立主页

很多开源项目托管平台都支持为托管的项目建立主页,但主页的维护方式都没有GitHub这么酷。大多数托管平台无非是开放一个FTP或类似服务,用户把制作好的网页或脚本上传了事,而在GitHub用户通过创建特殊名称的Git版本库或在Git库中建立特别的分支实现对主页的维护。

3.5.1. 创建个人主页

GitHub 为每一个用户分配了一个二级域名<user-id>.github.io,用户为自己的二级域名创建主页很容易,只要在托管空间下创建一个名为<user-id>.github.io的版本库,向其master分支提交网站静态页面即可,其中网站首页为index.html。下面以gotgithub用户为例介绍如何创建个人主页。

  • 用户gotgithub创建一个名为gotgithub.github.io的Git版本库。

    在GitHub上创建版本库的操作,参见“第3.1节 创建新项目”。

  • 在本地克隆新建立的版本库。

    $ git clone git@github.com:gotgithub/gotgithub.github.io.git
    $ cd gotgithub.github.io/
  • 在版本库根目录中创建文件index.html作为首页。

    $ printf "<h1>GotGitHub's HomePage</h1>It works.\n" > index.html
  • 建立提交。

    $ git add index.html
    $ git commit -m "Homepage test version."
  • 推送到GitHub,完成远程版本库创建。

    $ git push origin master
  • 访问网址: http://gotgithub.github.io/

    最多等待10分钟,GitHub就可以完成新网站的部署。网站完成部署后版本库的所有者会收到邮件通知。

    还有要注意访问用户二级域名的主页要使用HTTP协议非HTTPS协议。

3.5.2. 创建项目主页

如前所述,GitHub会为每个账号分配一个二级域名<user-id>.github.io作为用户的首页地址。实际上还可以为每个项目设置主页,项目主页也通过此二级域名进行访问。

例如gotgithub用户创建的helloworld项目如果启用了项目主页,则可通过网址http://gotgithub.github.io/helloworld/访问。

为项目启用项目主页很简单,只需要在项目版本库中创建一个名为gh-pages的分支,并向其中添加静态网页即可。也就是说如果项目的Git版本库中包含了名为gh-pages分支的话,则表明该项目提供静态网页构成的主页,可以通过网址http://<user-id>.github.io/<project-name>访问到。

下面以用户gotgithub的项目helloworld为例,介绍如何维护项目主页。

如果本地尚未从GitHub克隆helloworld版本库,执行如下命令。

$ git clone git@github.com:gotgithub/helloworld.git
$ cd helloworld

当前版本库只有一个名为master的分支,如果直接从master分支创建gh-pages分支操作非常简单,但是作为保存网页的gh-pages分支中的内容和master分支中的可能完全不同。如果不希望gh-pages分支继承master分支的历史和文件,即想要创建一个干净的gh-pages分支,需要一点小技巧。

若使用命令行创建干净的gh-pages分支,可以从下面三个方法任选一种。

第一种方法用到两个Git底层命令:git write-treegit commit-tree。步骤如下:

  • 基于master分支建立分支gh-pages

    $ git checkout -b gh-pages
  • 删除暂存区文件,即相当于清空暂存区。

    $ rm .git/index
  • 创建项目首页index.html

    $ printf "hello world.\n" > index.html
  • 添加文件index.html到暂存区。

    $ git add index.html
  • 用Git底层命令创建新的根提交,并将分支gh-pages重置。

    $ git reset --hard $(echo "branch gh-pages init." | git commit-tree $(git write-tree))
  • 执行推送命令,在GitHub远程版本库创建分支gh-pages

    $ git push -u origin gh-pages

第二种方法用到Git底层命令:git symbolic-ref。步骤如下:

  • git symbolic-ref命令将当前工作分支由master切换到一个尚不存在的分支gh-pages

    $ git symbolic-ref HEAD refs/heads/gh-pages
  • 删除暂存区文件,即相当于清空暂存区。

    $ rm .git/index
  • 创建项目首页index.html

    $ printf "hello world.\n" > index.html
  • 添加文件index.html到暂存区。

    $ git add index.html
  • 执行提交。提交完毕分支gh-pages完成创建。

    $ git commit -m "branch gh-pages init."
  • 执行推送命令,在GitHub远程版本库创建分支gh-pages

    $ git push -u origin gh-pages

第三种方法没有使用任何Git底层命令,是从另外的版本库获取提交建立分支。操作如下:

  • helloworld版本库之外创建另外一个版本库,例如helloworld-web

    $ git init ../helloworld-web
    $ cd ../helloworld-web
  • helloworld-web版本库中创建主页文件index.html

    $ printf "hello world.\n" > index.html
  • 添加文件index.html到暂存区。

    $ git add index.html
  • 执行提交。

    实际提交到master分支,虽然提交说明中出现的是gh-pages

    $ git commit -m "branch gh-pages init."
  • 切换到helloworld版本库目录。

    $ cd ../helloworld
  • helloworld-web版本库获取提交,并据此创建gh-pages分支。

    $ git fetch ../helloworld-web
    $ git checkout -b gh-pages FETCH_HEAD
  • 执行推送命令,在GitHub远程版本库创建分支gh-pages

    $ git push -u origin gh-pages

无论哪种方法,一旦在GitHub远程版本库中创建分支gh-pages,项目的主页就已经建立。稍后(不超过10分钟),用浏览器访问下面的地址即可看到刚刚提交的项目首页: http://gotgithub.github.io/helloworld/

除了以上通过命令行创建gh-pages分支为项目设定主页之外,GitHub还提供了图形操作界面。如图3-19所示。

../images/github-pages.png

图3-19:项目管理页面中的GitHub Pages选项

当在项目管理页面中勾选“GitHub Pages”选项,并按照提示操作,会自动在项目版本库中创建gh-pages分支。然后执行下面命令从版本库检出gh-pages分支,对项目主页进行相应定制。

$ git fetch
$ git checkout gh-pages

3.5.3. 使用专有域名

无论是用户主页还是项目主页,除了使用github.com下的二级域名访问之外,还可以使用专有域名。实现起来也非常简单,只要在master分支(用户主页所在版本库)或gh-pages分支(项目版本库)的根目录下检入一个名为CNAME的文件,内容为相应的专有域名。当然还要更改专有域名的域名解析,使得该专有域名的IP地址指向相应的GitHub二级域名的IP地址。

例如worldhello.net[1]是我的个人网站,若计划将网站改为由GitHub托管,并由账号gotgit通过个人主页提供服务,可做如下操作。

首先按照前面章节介绍的步骤,为账号gotgit设置账户主页。

  1. 在账户gotgit下创建版本库gotgit.github.io以维护该账号主页。

    地址: https://github.com/gotgit/gotgit.github.io/

  2. 将网站内容提交并推送到该版本库master分支中。

    即在gotgit.github.io版本库的根目录下至少包含一个首页文件,如index.html。还可以使用下节将要介绍到的 Jekyll 技术,让网页有统一的显示风格,此时首页文件可能并非一个完整的HTML文档,而是套用了页面模版。

  3. 至此当访问网址http://gotgit.github.io时,会将账号gotgit的版本库gotgit.github.io中的内容作为网站内容显示出来。

接下来进行如下操作,使得该网站能够使用专有域名www.worldhello.net提供服务。

  1. 在账号gotgit的版本库gotgit.github.io根目录下添加文件CNAME,文件内容为:www.worldhello.net

    参见: https://github.com/gotgit/gotgit.github.io/blob/master/CNAME

  2. 然后更改域名www.worldhello.net的IP地址,指向域名gotgit.github.io对应的IP地址(注意不是github.com的IP地址)。

    完成域名的DNS指向后,可试着用pingdig命令确认域名www.worldhello.netgotgit.github.io指向同一IP地址。

    $ dig @8.8.8.8 -t a www.worldhello.net
    ...
    ; ANSWER SECTION:
    www.worldhello.net.     81078   IN      A       204.232.175.78
    
    $ dig @8.8.8.8 -t a gotgit.github.io
    ...
    ; ANSWER SECTION:
    gotgit.github.io.      43200   IN      A       204.232.175.78

设置完成后用浏览器访问 http://www.worldhello.net/ 即可看到由账号gotgit的版本库gotgit.github.io维护的页面。若将域名worldhello.net(不带www前缀)也指向IP地址204.232.175.78,则访问网址http://worldhello.net/会发现GitHub体贴地将该网址重定向到正确的地址http://www.worldhello.net/

在账号gotgit下的其他版本库,若包含了gh-pages分支,亦可由域名www.worldhello.net访问到。

3.5.4. 使用Jekyll维护网站

Jekyll是一个支持Textile、Markdown等标记语言的静态网站生成软件,还支持博客和网页模版,由Tom Preston-Werner(GitHub创始人之一)开发。Jekyll用Ruby语言实现,项目在GitHub的托管地址: http://github.com/mojombo/jekyll/ ,专有的URL地址为:http://jekyllrb.com/

GitHub为用户账号或项目提供主页服务,会从相应版本库的master分支或gh-pages分支检出网页文件,然后执行 Jekyll 相应的命令对网页进行编译。因此在设计GitHub的用户主页和项目主页时都可以利用Jekyll,实现用Markdown等标记语言撰写网页及博客,并用页面模版实现网页风格的统一。

安装Jekyll最简单的方法是通过RubyGems安装,会自动将Jekyll依赖的directory_watcher、liquid、open4、maruku和classifier等Gem包一并安装。

$ gem install jekyll

如果安装过程因编译扩展模组遇到错误,可能是因为尚未安装所需的头文件,需要进行如下操作:

  • 对于Debian Linux、Ubuntu等可以用如下方法安装所需软件包:

    $ sudo apt-get install ruby1.8-dev
  • 如果是Red Hat、CentOS或Fedora等系统,使用如下命令安装:

    $ sudo yum install ruby-devel
  • 对于Mac OSX,可能需要更新RubyGems,如下:

    $ sudo gem update --system

Jekyll安装完毕,执行下面的命令显示软件版本:

$ jekyll -v
Jekyll 0.11.0

要学习如何用Jekyll设计网站,可以先看一下作者Tom Preston-Werner在GitHub上的个人网站是如何用Jekyll制作出来的。

克隆版本库:

$ git clone git://github.com/mojombo/mojombo.github.com.git

版本库包含的文件如下:

$ cd mojombo.github.com
$ ls -F
CNAME           _config.yml     _posts/         css/            index.html
README.textile  _layouts/       atom.xml        images/         random/

版本库根目录下的index.html文件不是一个普通的HTML文件,而是使用Liquid模版语言[2]定义的页面。

 1 ---
 2 layout: default
 3 title: Tom Preston-Werner
 4 ---
 5
 6 <div id="home">
 7   <h1>Blog Posts</h1>
 8   <ul class="posts">
 9     {% for post in site.posts %}
10       <li><span>{{ post.date | date_to_string }}</span> &raquo; <a href="{{ post.url }}">{{ post.title }}</a></li>
11     {% endfor %}
12   </ul>
   ...
63 </div>

为方便描述为内容添加了行号,说明如下:

  • 第1-4行是YAML格式的文件头,设定了该文件所使用的模版文件及模版中要用到的变量。

    凡是设置有YAML文件头的文件(目录_layouts除外)无论文件扩展名是什么,都会在Jekyll编译时进行转换。若源文件由Markdown等标记语言撰写(扩展名为.md.textile等),Jekyll还会将编译后的文件还将以扩展名.html来保存。

  • 其中第2行含义为使用default模版。

    对应的模版文件为_layouts/default.html

  • 第3行设定本页面的标题。

    在模版文件_layouts/default.html中用{{ page.title }}语法嵌入所设置的标题。下面是模版文件中部分内容:

    <head>
       <meta http-equiv="content-type" content="text/html; charset=utf-8" />
       <title>{{ page.title }}</title>
  • 第6行开始的内容绝大多数是标准的HTML语法,其中夹杂少量Liquid模版特有的语法。

  • 第9行和第11行,对于有着Liquid或其他模版编程经验的用户,不难理解其中出现的由“{%”和“%}”标识的指令是一个循环指令(for循环),用于逐条对博客进行相关操作。

  • 第10行中由“{{”和“}}”标识的表达式则用于显示博文的日期、链接和标题。

非下划线(_)开头的文件(包括子目录中文件),如果包含YAML文件头,就会使用Jekyll进行编译,并将编译后的文件复制到目标文件夹(默认为_site目录)下。对于包含YAML文件头并用标记语言Markdown等撰写的文件,还会将编译后的文件以.html扩展名保存。而以下划线开头的文件和目录有的直接忽略不予处理(如_layouts_site目录等),有的则需要特殊处理(如_post目录)。

目录_post用于保存博客条目,每个博客条目都以<YYYY>-<MM>-<DD>-<blog-tiltle>格式的文件名命名。扩展名为.md的为Markdown格式,扩展名为.textile的为Textile格式。这些文件都包含类似的文件头:

---
layout: post
title: How I Turned Down $300,000 from Microsoft to go Full-Time on GitHub
---

即博客使用文件_layouts/post.html作为页面模版,而不是index.html等文件所使用的_layouts/default.html模版。这些模版文件都采用Liquid模版语法。保存于_post目录下的博客文件编译后会以<YYYY>/<MM>/<DD>/<blog-title>.html文件名保存在输出目录中。

在根目录下还有一个配置文件_config.yml用于覆盖Jekyll的默认设置,例如本版本库中的设置。

markdown: rdiscount
pygments: true

第1行设置使用rdiscount软件包作为Markdown的解析引擎,而非默认的Maruku。第2行开启pygments支持。对于中文用户强烈建议通过配置文件_config.yml重设 markdown 解析引擎,默认的 Maruku 对中文支持不好,而使用 rdiscount 或 kramdown 均可。关于该配置文件的更多参数详见Jekyll项目维基[3]

编译Jekyll编辑网站只需在根目录执行jekyll命令,下面的命令是GitHub更新网站所使用的默认指令。

$ jekyll --pygments --safe

现在执行这条命令,就会将整个网站创建在目录_site下。

如果没有安装Apache等Web服务器,还可以使用Jekyll的内置Web服务器。

$ jekyll --server

默认在端口4000开启Web服务器。

网址 http://gitready.com/ 是一个提供Git使用小窍门的网站,如图3-20所示。

../images/gitready.png

图3-20:Git Ready 网站

你相信这是一个用Jekyll制作的网站么?看看该网站对应的IP,会发现其指向的正是GitHub。研究GitHub上 gitready 用户托管的版本库,会发现en版本库的gh-pages分支负责生成gitready.com网站,de版本库的gh-pages分支负责生成德文网站de.gitready.com,等等。而gitready版本库则是各种语种网站的汇总。

我的个人网站也使用Jekyll构建并托管在GitHub上,网址:http://www.worldhello.net/


[1]“Hello, world”最为程序员所熟知,2002年申请不到helloworld相关域名便退而求其次,申请了 worldhello.net。
[2]http://liquidmarkup.org/
[3]https://github.com/mojombo/jekyll/wiki/configuration