GitHub-Pages
翻译自GitHub Pages的Help页面———https://help.github.com/categories/github-pages-basics/
欢迎大家关注我的github: http://getcha22.github.io/
欢迎大家一起翻译。初次翻译,有错误希望大家多提醒。
GitHub 帮助
目录
什么是GitHub Pages? (完工)
个人/组织页面和项目页面(完工)
通过自动生成器创建页面(完工)
通过手动的方式创建页面 (完工)
使用Jekyll工具创建页面 (完工)
网站自定义域名
为页面自定义域名
通过DNS提供商配置CNAME文件的几点提示
在你的库中添加CNAME文件
通过DNS提供商配置一条A记录的几点提示
延伸说明
什么是GitHub Pages?
GitHub Pages是通过我们的网站托管和发布的公共网页。
你可以通过在线生成器创建和发布GitHub Pages页面。如果你偏爱本地操作,你可以使用Mac和Windows的GUI软件,或者是命令行。
页面通过HTTP协议传播,不是HTTPS。建议您不要在发送密码和信用卡号码的时候使用它
提示:GitHub Pages在互联网上是公开的,即便对应的是私人库,如果在您的GitHub Pages的库中有敏感数据,建议你在发布之前移走他们。
个人/组织页面和项目页面
GitHub Pages 有两种基础类型:个人/组织的GitHub Pages和项目的GitHub Pages。
他们十分相似,但是也有一些不同点需要留意。
两种GitHub Pages都通过HTTP协议,而不是HTTPS,建议您不要在私密信息上使用它们,比如发送密码或者信用卡号。
请注意GitHub Pages是公开发布的,即便你的库是私人库。
个人&组织页面(User&Organization Pages)
个人&组织页面放在一个特殊的库中,你需要用你的账户名去命名这个项目。
库需要使用
uesrname.github.io
命名
master
分支将被用来建立和发布你的GitHub Pages网站。
在创建个人或者组织页面对应的库时,你只可以使用自己的账户名,像joe/bob.github.io
不能用来建立个人页面。
当个人页面被成功建立后,通过http(s)://username.github.io
访问。
建立你自己的GitHub Pages
任何验证了email地址的个人账户,都可以建立个人页面,他们也可以使用一键部署的按钮来自动生成页面
可以给库进行推送并且验证了email地址的组织库成员,都可以建立组织库,为了让过程自动化,你建立一个machine user作为你组织的成员,无法在项目库中使用一键部署。
项目页面(Project Pages)
项目页面保存在当前项目库中,这点与个人/组织页面不同,所有的个人账户和组织账户都可以创建项目页面。
个人账户创建的项目页面可以通过http(s)://<username>.github.io/<projectname>
访问,对于组织账户可以通过URLhttp(s)://<orgname>.github.io/<projectname>
访问。
个人用户和组织用户创建页面的步骤是相同的。
项目页面和个人/组织页面大体相同,以下是一点差异:
项目页面使用
gh-pages
分支(个人组织页面使用master
分支)。
如果没有自定义域名,项目页面被运行在个人页面的子路径下:username.github.io/projectname
如果为个人/组织页面自定义了域名,那么所有组织页面被重定向到这个域名下,当然,个人账户创建的项目页面依然可以通过username.github.io/projectname
访问,组织账户创建的项目页面依然可以通过orgname.github.io/projectname
访问
自定义域名后才可以自定义404页面
通过自动生成器创建页面
你可以使用GitHub的页面自动生成功能,快速为项目,个人/组织创建一个网站。
个人/组织页面
为了生成用户/组织页面网站,你需要创建一个名为username.github.io
的项目,个人用户名或者组织名称必须是已经拥有的,否则GitHub Pages无法建立。自动页面生成功能在项目库设置中可以找到,有关个人/组织页面的介绍,可以阅读上面的说明个人/组织页面和项目页面
项目页面
通过页面自动生成功能,你可以为任何项目库创建GitHub Pages。
自动生成功能
1.登陆GitHub,进入该库的主页。
2.在该库右侧的边栏,点击
setting
3.点击下侧
Automatic Pages Generator
按钮
4.在Markdown编辑器中编辑自己的内容
5.点击
Continue To Layouts
按钮。6.在我们提供的主题中预览你的内容
7.当你选择了自己喜欢的主题后,点击
Publish Page
你的页面产生之后,你可以得到这个页面对应的HTML代码,如果使用自动生成功能生成的是项目页面网站,你需要fetch(下载)
和checkout(切换)
到新的分支.
cd repository //切换到repository对应的目录
git fetch origin //从远程仓库更新
# remote: Counting objects: 92, done.
# remote: Compressing objects: 100% (63/63), done.
# remote: Total 68 (delta 41), reused 0 (delta 0)
# Unpacking objects: 100% (68/68), done.
# From https://github.com/user/repo.git
# * [new branch] gh-pages -> origin/gh-pages
git checkout gh-pages //切换到gh-pages分支,需要您先创建
# Branch gh-pages set up to track remote branch gh-pages from origin.
# Switched to a new branch 'gh-pages'
如果生成的是个人页面,代码会在master
分支,而不是gh--pages
分支,所以通过checkout(切换)
master(主)
分支,之后再pull
。
cd repository
git checkout master
# Switched to branch 'master'
git pull origin master
# remote: Counting objects: 92, done.
# remote: Compressing objects: 100% (63/63), done.
# remote: Total 68 (delta 41), reused 0 (delta 0)
# Receiving objects: 100% (424/424), 329.32 KiB | 178 KiB/s, done.
# Resolving deltas: 100% (68/68), done.
# From https://github.com/user/repo.git
# * branch master -> FETCH_HEAD
# Updating abc1234..def5678
# Fast-forward
# index.html | 265 ++++
# ...
# 98 files changed, 18123 insertions(+), 1 deletion(-)
# create mode 100644 index.html
通过手动的方式创建页面
如果你对于Git命令行比较熟,你可以直接手动创建项目页面
创建一个新的clone(克隆)
建立项目页面,你需要在你的项目库中建立"孤儿"分支(这个分支不能与以前的分支冲突),最安全的办法就是
直接重新clone项目:
git clone github.com/user/repository.git
# Clone our repository
# Cloning into 'repository'...
# remote: Counting objects: 2791, done.
# remote: Compressing objects: 100% (1225/1225), done.
# remote: Total 2791 (delta 1722), reused 2513 (delta 1493)
# Receiving objects: 100% (2791/2791), 3.77 MiB | 969 KiB/s, done.
# Resolving deltas: 100% (1722/1722), done.
创建gh-pages
分支
如果你有了一个干净的项目库,你就可以创建一个gh-pages
分支,之后把你工作区和暂存区中的所有内容移走:
cd repository //切换目录
git checkout --orphan gh-pages //创建一个新的分支,无父分支,意味着里面是无任何文件的
# Creates our branch, without any parents (it's an orphan!)
# Switched to a new branch 'gh-pages'
git rm -rf . //删除之前工作区可能有的所有文件
# Remove all files from the old working tree
# rm '.gitignore'
增加内容,进行推送
现在你有一个空的工作区,你可以在这个分支上创建内容,推送到GitHub,例如:
echo "My Page" > index.html
git add index.html
git commit -a -m "First pages commit"
git push origin gh-pages
你的GitHub页面网站这是应该已经建立了,如果你没有成功的话,会收到一封email。
载入创建的`GitHub Pages
在你推送到gh-pages
后,项目页面网站可以通过http(s)://<username>.github.io/<projectname>
访问。注意:在你推送之后,这个页面是公开的,即便你的库是私人库。
使用Jekyll工具创建页面
除了支持常规的HTML内容,GitHub Pages还支持Jekyll(哲基尔),它是一个简单的博客形态的静态页面生成器,它让在创建全站公用的Header,Footer后,不需要在每个页面上复制这些部分。它还提供一些高级模板功能。
使用Jekyll
当你把内容推送到仓库中指定分支后,jekyll就可以被使用了。对于个人页面,使用username.github.io
仓库中的master
分支,对于项目页面,可以在当前项目仓库中使用gh-pages
分支,因为一个正常的HTML网页也是有效的,Jekyll有完整的使用文档,涵盖他的特点和用法。提交符合Jekyll格式的文件,你就可以使用了。
安装Jekyll
我们强烈推荐安装Jekyll在你电脑上来预览你的网站,这样在你将网站推送到GitHub Pages前,就可以核实错误
为了保障你的电脑可以完美使用GitHub Pages,你可以使 (the GitHub Pages Gem)[https://github.com/github/pages-gem]来下载你需要的依赖.现在我们先来安装Jekyll:
1.Ruby-Jekyll需要Ruby语言环境,如果你使用Mac,你很可能已经预装Ruby环境了,你可以打开命令行终端,允许命令ruby --version
来确认是否安装。你的Ruby至少应该在2.0.0以上,如果你已经获得了Ruby,你可以跳到第二步,否则,参考(这个说明)[https://www.ruby-lang.org/en/downloads/]安装Ruby。
2.Bundler-Bundler是一个包管理工具,如果你想要在本地建立GitHub Pages,使用它来控制Ruby环境的软件,比如Jekyll会方便很多。如果你还没有按照过Bundler,你可以通过命令行gem install bundler
来安装它。
3.Jekyll-重要的来了,你需要在你的库中创建一个叫做Gemfile
的文件,同时需要增加一行代码gem 'github-pages'
,这些完成之后,可以运行bundle install
来自动安装。如果您跳过了第二步,没有安装包管理器,你可以需要通过命令行gem install github-pages
,此时可能会遇到一些麻烦。
下面是Gemfile
的的例子:
source 'https://rubygems.org'
gem 'github-pages'
设置jekyll
打开命令行工具
-
使用命令
jekyll new
加网站的名字来自动生成jekyll网站jekyll new YOUR-JEKYLL-SITE
New jekyll site installed in /Users/YOUR-USERNAME/YOUR-JEKYLL-SITE -
使用
cd
进入jekyll网站根目录cd YOUR-JEKYLL-SITE
-
进入之后即可将它初始化为git仓库
git init
Initialized empty Git repository in /Users/YOUR-USERNAME/YOUR-JEKYLL-SITE/.git/
更详细的信息,可以参考jekyll快速使用指南
运行Jekyll
使用
git checkout
命令移动到该去的分支(个人/组织页面master/项目库gh-pages),在github pages文件的根目录,使用
bundle exec jekyll serve
来执行jekyll参考提示,使用
http://localhost:4000
来访问网站
更多的jekyll命令,可以参考Jekyll文档
检查Jekyll的更新
Jekyll是一个开源的项目,会频繁的进行升级,github pages也会紧跟更新,如果您本地的Jekyll版本过久,可能在推送到github pages之后会发生不同,为了保证Jekyll的版本更新,您可以bundle update
。
配置Jekyll
创建了_config.yml
文件后,您可以自定义jekyll的设置
默认情况
在GitHub Pages网站使用自定义域名
两类域名可以被重定向到GitHub Pages网站:子域名和顶级域名。
子域名
通过你的DNS服务提供商,可以(配置一条CNAME
记录)[https://help.github.com/articles/tips-for-configuring-a-cname-record-with-your-dns-provider/]
我们有以下原因,建议你强烈使用子域名:
引用文字
子域名不会受到GitHub服务器底层IP地址变化的影响
页面将会加载显著变快,因为DOS服务可以更有效
顶级域名
顶级域名通常需要配置A
ALIAS
ANAME
记录,并且常常分配一个或者多个IP地址
我们建议使用自定义子域名,而不是顶级域名。
1.HTTPS and HTTP Difference
https://www.instantssl.com/https-tutorials/what-is-https.html