深入 Github 主页

jopen 8年前


上一篇我们讲了 如何打造一个自动化的前端项目 ,大致提了一下如何用 Github 作为主页来展示。这一章我们就来详细说说 Github 主页。

什么是 Github 主页

Github 提供给每个用户的一个用于运行静态页面的地址。包括一个二级域名( http://[Github 用户名].github.io/ )和存放文件的版本库。按照库的类型可以分为 个人主页项目主页

下面我们就来讲讲如何创建这两种主页以及注意事项。

个人(组织)主页

一般是用来作为你的个人(或组织)信息展示的主页。

注意:

  • 1、创建的版本库必须命名为 [Github 用户名].github.io
  • 2、必须将要展示的内容放到 master 分支下
  • 3、访问地址为 http://<Github 用户名>.github.io

步骤:

这里我以我的 Github 账户 awesomes-cn 为例来讲解:

1、在本地创建一个 awesomes-cn.github.io 文件夹:

mkdir awesomes-cn.github.io 

创建自己的主页的项目,具体可参考 如何打造一个自动化的前端项目 ,这里我们简单地只创建一个 index.html 页面。

echo "My Page" > index.html 

2、在 Github 上创建名为 awesomes-cn.github.io 的个人项目。

3、回到本地项目根目录,依次执行:

git init     git add .    git commit -m 'init project'    git remote add origin git@github.com:awesomes-cn/auto-web.git    git push -u origin master 

上面的命令将本地项目上传到了 Github 上,现在你可以通过 http://awesomes-cn.github.io 来访问你的个人主页了,注意这里也许会有延迟。

项目主页

主要用来为每个项目创建说明文档主页。

注意:

  • 1、必须将要展示的内容放到 gh-pages 分支下
  • 2、访问地址为 http://<Github 用户名>.github.io/<项目名>

一般我们是在一个项目自身完成后才去创建项目主页,所以在我们创建项目主页之前,该项目已经存在了。 下面我们就给 awesomes-cn/emoji 这个项目添加一个项目主页。

步骤:

1、首先我们给项目创建一个 gh-pages 分支:

git checkout --orphan gh-pages 

上面的指令是创建一个 gh-pages 分支,并切换到该分支。 --orphan 表示该分支是全新的,不继承原分支的提交历史(默认 git branch gh-pages 创建的分支会继承 master 分支的提交历史,所以就不纯净了)。不过需要注意的是,这里 git branch 是显示不出 gh-page 分支的,需要做一次提交才行。

2、别急,接下来把新分支中的文件删掉:

git rm -rf .  rm '.gitignore' 

3、然后创建我们需要的静态页面文件,这里象征性地创建一个 index.html 并写入内容:

echo "My Page" > index.html 

4、然后开始做提交:

git add index.html  git commit -a -m "First pages commit"  git push origin gh-pages 

现在通过 git branch 就可以看到 gh-page 分支了。

然后访问 http://awesomes-cn.github.io/emoji 就可以看到我们的项目主页了。

注意事项

1、如果你的项目名开始或结尾包含破折号(如 emoji--emoji ),或者包含连续破折号(如 web--emoji ),那么Linux用户访问的时候会报错,你需要移除项目名中的非字母数字的字符。

2、 大家也许注意到了,个人主页的地址是 http://awesomes-cn.github.io/ ,而项目主页的地址是类似 http://awesomes-cn.github.io/emoji ,事实上就是一个相对于个人主页项目的二级访问目录。

那么问题来了,如果个人主页项目里面有一个 emoji 文件夹,里面也有相应的静态页面。访问 http://awesomes-cn.github.io/emoji 时究竟访问的是哪个项目呢?

经过测试,实际上访问的是 awesomes-cn/emoji 的项目主页,也就是说个人主页的 emoji 目录是访问不到的。

所以大家要注意不要造成这两者的命名冲突。

到此为止,我们已经实现了通过命令行手动创建项目主页了,不过这页面也着实太丑了。不行,我得好好美化一下,设计是件艰苦差事,幸好Github为我们提供了一个页面自动生成器。

页面自动生成器

这是Github 为我们提供的可视化生成主页的工具,具体操作如下:

在此之前,我们将上面手动生成的 gh-pages 分支删掉:

删除本地分支(需要切换到非 gh-pages 的分支):

 git checkout master   git branch -D gh-pages 

然后删除远程分支:

git push origin --delete gh-pages 

OK 接下来我们就可以开始用自动生成的方式来创建项目主页了。

1、在 Github 上切换到你的项目主页,点击 Settings 设置按钮

2、点击 Launch automatic page generator 启动页面自动生成器

3、进入主页设计页面(这里使用的是 Markdown 编辑器),并填写相关的信息,还可以添加 Google 的统计插件。注意,这里我们一般可以通过加载 README.md 文件来直接从中读取内容,否则你就得自己手动编写。

4、点击 Continue To Layouts 按钮,进入模板选择页面。这里你可以选择自己喜欢的模板样式,是不是很漂亮?而且很多模板相信大家都在一些项目的主页中看到过。

5、选择好模板后,可以点击左上角的 Publish page 发布页面,然后就可以看到成功提示了。

6、最后,我们将 http://awesomes-cn.github.io/emoji/ 设置成项目主页

整个过程完成后,你可以看到在你的项目中自动生成了一个新的分支。没错,就是 gh-pages ,可以看到里面有一些样式和脚本文件。如果你对其中的某些部分不满意,或者想添加新的页面,那么可以将该分支 pull 到本地进行修改。

首先将分支拉到本地:

 git fetch origin 

然后切换到 gh-pages 分支:

 git checkout gh-pages 

接下来就可以做自己的修改了。

注意:如果你是在个人主页中使用页面自动生成器,那么最终的文件会生成到 master 分支下。因为上面我们说过个人主页是 master 分支,项目主页是 gh-pages 分支。所以可以直接

 git pull origin master 

第三方工具

当然,除了上面两种方式,还有很多第三方的工具来帮助我们构建主页,如 jekyll ,这里我就不详细讲了,感兴趣的同学可以了解一下。

域名绑定

有的同学不喜欢 Github 给的二级域名,想设置自己的域名来访问,很简单,我们这里以我的个人主页项目 来介绍。

1、来到 项目主页 ,切换到 master 分支下(注意:如果是个人主页则切换到 master 分支,如果是项目主页则切换到 gh-pages 分支),新建一个文件:

2、将文件命名为 CNAME ,然后添加你要解析的域名 home.awesomes.cn (注意这里不是 http://home.awesomes.cn 且只能填写一个域名),我这里用的是一个二级域名。

然后填写提交信息并直接提交合并。

3、域名解析。这里我用的是万网的域名,我们做下面的解析操作:

  • 记录类型:CNAME
  • 主机记录: home
  • 记录值:awesomes-cn.github.io

接下来你就可以直接访问 http://home.awesomes.cn/ 来替代 http://awesomes-cn.github.io 了,是不是很简单。

注意:

我这里是将 home.awesomes.cn 解析到了个人主页项目上,访问 http://home.awesomes.cn/emoji 仍然是可以访问到 emoji 项目主页的。

但是如果我把这个 CNAME 文件创建到 emoji 项目的 gh-pages 分支下(即直接解析 emoji 项目主页),那么访问 http://home.awesomes.cn 就相当于访问 http://awesomes-cn.github.io/emoji 了,而个人主页项目也就访问不到了。

总结

一般情况下,我们都会选择使用 页面自动生成器来创建项目主页,因为更加方便和美观。但在此之前我们应该通过手动操作来知晓其中的原理。

上面的例子都使用了我的项目来做谅解,实际使用过程中请将对应的地方换成自己的项目名。

官方文档: https://help.github.com/categories/github-pages-basics/