Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 127 lines (78 sloc) 7.963 kb
21824f1 @mojombo initial structure
mojombo authored
1 ---
2 title: Home
83c05e1 @mojombo make it awesome
mojombo authored
3 layout: wikistyle
21824f1 @mojombo initial structure
mojombo authored
4 ---
5
6 Introduction to Pages
7 =====================
8
83c05e1 @mojombo make it awesome
mojombo authored
9 The GitHub Pages feature allows you to publish content to the web by simply pushing content to one of your GitHub hosted repositories. There are two different kinds of Pages that you can create: User Pages and Project Pages.
10
f70f0f0 @tekkub User pages work for orgs too
tekkub authored
11 User & Organization Pages
12 -------------------------
83c05e1 @mojombo make it awesome
mojombo authored
13
f8ce53d @tekkub Only the master branch for user pages repos
tekkub authored
14 Let's say your GitHub username is "alice". If you create a GitHub repository named `alice.github.com`, commit a file named `index.html` into the `master` branch, and push it to GitHub, then this file will be automatically published to [http://alice.github.com/](http://alice.github.com/).
83c05e1 @mojombo make it awesome
mojombo authored
15
16 On the first push, it can take up to ten minutes before the content is available.
17
f70f0f0 @tekkub User pages work for orgs too
tekkub authored
18 The same works for organizations. If your org account is named "PlanEx", creating the repo `planex.github.com` under the org will publish pages to <http://planex.github.com/>.
19
b9bb14e @mojombo clarify example citations
mojombo authored
20 Real World Example: [github.com/defunkt/defunkt.github.com](http://github.com/defunkt/defunkt.github.com/) &rarr; [http://defunkt.github.com/](http://defunkt.github.com/).
83c05e1 @mojombo make it awesome
mojombo authored
21
22 Project Pages
23 -------------
24
25 Let's say your GitHub username is "bob" and you have an existing repository named `fancypants`. If you create a new root branch named `gh-pages` in your repository, any content pushed there will be published to [http://bob.github.com/fancypants/](http://bob.github.com/fancypants/).
26
0cafcc3 @tekkub Better warning (uncommitted files are lost, not just uncommitted changes...
tekkub authored
27 In order to create a new root branch, first ensure that your working directory is clean by committing or stashing any changes. <span style="color: #a00;">The following operation will lose any uncommitted files! You might want to run this in a fresh clone of your repo.</span>
83c05e1 @mojombo make it awesome
mojombo authored
28
a8c3d64 @tekkub Add "$" to console pre blocks for consistancy
tekkub authored
29 $ cd /path/to/fancypants
27af78f @tekkub Revert "New command!"
tekkub authored
30 $ git symbolic-ref HEAD refs/heads/gh-pages
31 $ rm .git/index
32 $ git clean -fdx
83c05e1 @mojombo make it awesome
mojombo authored
33
34 After running this you'll have an empty working directory (don't worry, your main repo is still on the `master` branch). Now you can create some content in this branch and push it to GitHub. For example:
35
a8c3d64 @tekkub Add "$" to console pre blocks for consistancy
tekkub authored
36 $ echo "My GitHub Page" > index.html
37 $ git add .
38 $ git commit -a -m "First pages commit"
39 $ git push origin gh-pages
83c05e1 @mojombo make it awesome
mojombo authored
40
41 On the first push, it can take up to ten minutes before the content is available.
42
43 Real World Example: [github.com/defunkt/ambition@gh-pages](http://github.com/defunkt/ambition/tree/gh-pages) &rarr; [http://defunkt.github.com/ambition](http://defunkt.github.com/ambition).
44
c664cfd @tekkub Add project page generator section
tekkub authored
45 ### Project Page Generator
46
47 If you don't want to go through the steps above to generate your branch, or you simply would like a generic page, you can use our page generator to create your gh-pages branch for you and fill it with a default page.
48
a999d1c @c00kiemon5ter Update images of 'Project Page Generator' section
c00kiemon5ter authored
49 First navigate to your project and click the 'Admin' button on the top right
50
51 > ![Admin button](admin_button.png)
52
53 Then check the 'GitHub Pages' check box.
54
55 > ![github pages checkbox](ghpages_checkbox.png)
56
57 A pop-up will appear. Click on the 'Automatic GitHub Page Generator'
58
59 > ![github pages popup generator](ghpages_popup.png)
c664cfd @tekkub Add project page generator section
tekkub authored
60
61 After your page is generated, you can check out the new branch:
62
63 $ cd Repos/ampere
64 $ git fetch origin
65 remote: Counting objects: 92, done.
66 remote: Compressing objects: 100% (63/63), done.
67 remote: Total 68 (delta 41), reused 0 (delta 0)
68 Unpacking objects: 100% (68/68), done.
69 From git@github.com:tekkub/ampere
70 * [new branch] gh-pages -> origin/gh-pages
71 $ git checkout -b gh-pages origin/gh-pages
72 Branch gh-pages set up to track remote branch refs/remotes/origin/gh-pages.
73 Switched to a new branch "gh-pages"
74
83c05e1 @mojombo make it awesome
mojombo authored
75 Using Jekyll For Complex Layouts
76 ================================
77
78 In addition to supporting regular HTML content, GitHub Pages support [Jekyll](http://github.com/mojombo/jekyll/), a simple, blog aware static site generator written by our own Tom Preston-Werner. Jekyll makes it easy to create site-wide headers and footers without having to copy them across every page. It also offers intelligent blog support and other advanced templating features.
79
80 Every GitHub Page is run through Jekyll when you push content to your repo. Because a normal HTML site is also a valid Jekyll site, you don't have to do anything special to keep your standard HTML files unchanged. Jekyll has a thorough [README](http://github.com/mojombo/jekyll/blob/master/README.textile) that covers its features and usage.
81
0e1dc73 @mojombo update with 0.5.0 info
mojombo authored
82 As of April 7, 2009, you can configure most Jekyll settings via your `_config.yml` file. Most notably, you can select your permalink style and choose to have your Markdown rendered with RDiscount instead of the default Maruku. The only options we override are as follows:
83
10b4866 @mojombo update for Jekyll 0.6.0
mojombo authored
84 safe: true
0e1dc73 @mojombo update with 0.5.0 info
mojombo authored
85 source: <your pages repo>
86 destination: <the build dir>
87 lsi: false
88 pygments: true
89
83c05e1 @mojombo make it awesome
mojombo authored
90 If your Jekyll site is not transforming properly after you push it to GitHub, it's useful to run the converter locally so you can see any parsing errors. In order to do this, you'll want to use the same version that we use.
91
5765f56 @tmm1 jekyll 0.11.0
tmm1 authored
92 We currently use <span style="font-weight: bold; color: #0a0;">Jekyll 0.11.0</span> and run it with the equivalent command:
83c05e1 @mojombo make it awesome
mojombo authored
93
10b4866 @mojombo update for Jekyll 0.6.0
mojombo authored
94 jekyll --pygments --safe
83c05e1 @mojombo make it awesome
mojombo authored
95
17e4197 @mojombo add .nojekyll instructions
mojombo authored
96 As of December 27, 2009, you can completely opt-out of Jekyll processing by creating a file named `.nojekyll` in the root of your pages repo and pushing that to GitHub. This should only be necessary if your site uses directories that begin with an underscore, as Jekyll sees these as special dirs and does not copy them to the final destination.
97
83c05e1 @mojombo make it awesome
mojombo authored
98 If there's a feature you wish that Jekyll had, feel free to fork it and send a pull request. We're happy to accept user contributions.
99
b9bb14e @mojombo clarify example citations
mojombo authored
100 Real World Example: [github.com/pages/pages.github.com](http://github.com/pages/pages.github.com/) &rarr; [http://pages.github.com/](http://pages.github.com/).
83c05e1 @mojombo make it awesome
mojombo authored
101
1cbb4a0 @tekkub Lets stop calling that CNAME, since it might be an A record
tekkub authored
102 Custom Domains
103 ==============
83c05e1 @mojombo make it awesome
mojombo authored
104
baae2bb @defunkt freedom
defunkt authored
105 GitHub Pages allows you to direct a domain name of your choice at your Page.
83c05e1 @mojombo make it awesome
mojombo authored
106
107 Let's say you own the domain name [example.com](http://example.com). Furthermore, your GitHub username is "charlie" and you have published a User Page at [http://charlie.github.com/](http://charlie.github.com/). Now you'd like to load up [http://example.com/](http://example.com) in your browser and have it show the content from [http://charlie.github.com/](http://charlie.github.com/).
108
109 Start by creating a file named `CNAME` in the root of your repository. It should contain your domain name like so:
110
111 example.com
112
21ef258 @tekkub Rewordify
tekkub authored
113 Push this new file up to GitHub. The server will set your pages to be hosted at [example.com](http://example.com), and create redirects from [www.example.com](http://www.example.com) and [charlie.github.com](http://charlie.github.com/) to [example.com](http://example.com).
83c05e1 @mojombo make it awesome
mojombo authored
114
38a1bd7 @tekkub Fix instructions for DNS
tekkub authored
115 Next, you'll need to visit your domain registrar or DNS host and add a record for your domain name. For a sub-domain like `www.example.com` you would simply create a CNAME record pointing at `charlie.github.com`. If you are using a top-level domain like `example.com`, you must use an A record pointing to `207.97.227.245`. *Do not use a CNAME record with a top-level domain,* it can have adverse side effects on other services like email. Many DNS services will let you set a CNAME on a TLD, even though you shouldn't. Remember that it may take up to a full day for DNS changes to propagate, so be patient.
83c05e1 @mojombo make it awesome
mojombo authored
116
076411a @tekkub Add note about 404 pages.
tekkub authored
117 Real World Example: [github.com/mojombo/mojombo.github.com](http://github.com/mojombo/mojombo.github.com/) &rarr; [http://tom.preston-werner.com/](http://tom.preston-werner.com/).
118
508d3ab @surma A little clarification for custom domains
surma authored
119 The above also works for project & organization pages, of course.
120
076411a @tekkub Add note about 404 pages.
tekkub authored
121 Custom 404 Pages
122 ================
123
08c4d2a @tekkub Make filename a code span
tekkub authored
124 If you provide a `404.html` file in the root of your repo, it will be served instead of the default 404 page. Note that Jekyll-generated pages will not work, it <i>must</i> be an html file.
076411a @tekkub Add note about 404 pages.
tekkub authored
125
dad5152 @tekkub Give that ANOTHER try...
tekkub authored
126 Real World Example: [http://github.com/tekkub/tekkub.github.com/blob/master/404.html](http://github.com/tekkub/tekkub.github.com/blob/master/404.html) &rarr; [http://tekkub.net/404.html](http://tekkub.net/404.html).
Something went wrong with that request. Please try again.