中财网本兮没放弃:Publishing a Blog with GitHub Pages and Jekyll
来源：百度文库 编辑：中财网 时间：2024/05/11 04:40:52
Publishing a Blog with GitHub Pages and Jekyll
8.5.09 by Tyler Hunt
Many people turn to GitHub for Git repository hosting, but did you know every GitHub account also includes basic web hosting? Not only is it free, but if you know how to push to a Git repository, you know how to deploy to GitHub Pages. It’s as simple as creating a repository called username.github.com.
Getting Started
We’re going to walk through the process of setting up and pushing out your first GitHub Pages page. If you’re already familiar with HTML and Git, you’ll see that there’s nothing really new here. Just bear with me and we’ll get to the good stuff below.
First, we’ll create a directory for our new site.
view sourceprint?1.mkdir envylabs.github.com2.cd envylabs.github.comThen, let’s create an index.html file that looks something like this:
01.02.<html>03.<head>04.<title>Envy Labstitle>05.head>06. 07.<body>08.<h1>Envy Labsh1>09.body>10.html>Initialize the repository and commit our new index file.
view sourceprint?1.git init2.git add index.html3.git commit -m 'Initial commit.'Then push to GitHub and cross your fingers.
view sourceprint?1.git remote add origin git@github.com:envylabs/envylabs.github.com.git2.git push origin masterYour page should be live at http://username.github.com/ in about 10 minutes.
Subsequent changes seem to be picked up almost immediately, and updating your site is as simple as adding and updating files and pushing to GitHub.
Jekyll
Editing static HTML files works just fine, but it isn’t the most practical way to maintain a site. This is where a tool like Jekyll really shines. It’s is a static site generation tool built by Tom Preston-Werner. It lets you build out your site using HTML, Markdown, or Textile and then runs everything through the Liquid templating engine. It supports layouts and a few other tricks to make it easy to manage a blog.
We’re going to install it locally so we can preview our page before we push it up to GitHub. It’s a good idea to match your local version to the one that GitHub is using. You can find the version of Jekyll they’re using on the GitHub Pages home page.
view sourceprint?1.sudo gem install mojombo-jekyll -s http://gems.github.com -v 0.5.2Starting with our original version of the site—just a simple index.html file—we can begin to see the power of Jekyll by creating a layout and converting our index file to use it.
Create the file _layouts/default.html.
view sourceprint?01.02.<html>03.<head>04.<title>{{ page.title }}title>05.head>06. 07.<body>08.<h1>{{ page.title }}h1>09. 10.{{ content }}11.body>12.html>Then update index.html.
view sourceprint?1.---2.layout: default3.title: Envy Labs4.---5. 6.Welcome!The “YAML Front Matter” at the top will let Jekyll know that we want this file processed wrapped with the template named default, and will set a variable called page.title that we can use in our templates. The rest of the page will be output in the layout where we have the {{ content }} tag.
To see it in action, run jekyll --pygments from the root of your site (the --pygments option will enable syntax highlighting for code snippets). The generated output is put into the _site subdirectory. Open up _site/index.html in your browser to see what it produced.
A simple git push is all you need to update the live site. Every time you push to GitHub it will automatically run jekyll --pygments on it before publishing.
Blogging with Jekyll
Jekyll has some rudimentary support built in for generating blogs. It relies on a special naming scheme where all of your posts go under the _posts subdirectory, and each post is named year-month-day-the-title-of-the-post.format where format is one of html, markdown, or textile depending on your markup language of choice.
For the first post, create the file _posts/2009-08-05-first-post.markdown.
view sourceprint?1.---2.layout: default3.title: First Post4.---5. 6.This will be the best blog ever.Now, let’s update our index to list out the five most recent posts.
view sourceprint?01.---02.layout: default03.title: Envy Labs04.---05. 06.{% for post in site.posts limit:5 %}07.<h2><a href="{{ post.url }}">{{ post.title }}a>h2>08.{{ post.content }}09.<em>Posted on {{ post.date | date_to_long_string }}.em>10.{% endfor %}See the page on template data for a full listing of the available variables.
While this simple layout works, you can extend the concepts you’ve learned to flesh out the design and features of your blog. For instance, you might want to create a separate layout for your individual posts, or generate a feed using an XML file with the same YAML front matter and Liquid tags you’ve already seen.
If you’d like comments on your Jekyll blog, check out Disqus. You can add comments to a post using JavaScript with a snippet like this.
view sourceprint?1.<a href="{{ page.url }}#disqus_thread">View Commentsa>2.<div id="disqus_thread">div>3.<script type="text/javascript" src="http://disqus.com/forums/[your-site-name]/embed.js">script>There are some additional resources further down that you might find useful.
Custom Domains
GitHub pages also supports pointing your own domain to your site, but it only works on paid accounts and repositories with contributors who have paid accounts. It’s simple to set up, but may take around a day for the changes to fully propagate.
Start by creating the file CNAME in the root of your site containing the domain name you’d like to have pointed to your GitHub Pages site.
view sourceprint?1.pages.envylabs.comThen, after you add this file and push to GitHub, you’ll need to modify your DNS settings by adding a CNAME entry for your desired domain that points to your GitHub Pages domain. In our example, we could create pages.envylabs.com and point it to envylabs.github.com.
That’s all there is to it. Wait patiently, and you should be good to go.
Project Pages
We’ve seen how to create a site for your GitHub account, but you can also create individual sites for each of your projects at http://username.github.com/project-name. This could be used for a full on sub-site for each of your projects, or just as a place to stash RDocs or other documentation.
GitHub will look for a gh-pages branch on each of your projects, and will use that as /project-name on your GitHub Pages site if one is found. The tricky part here is creating a branch without ancestry. I’ve seen a few different ways to do this, but none are easy and all have caveats.
This is the method that GitHub preaches. You’ll need to make sure you don’t have any uncommitted changes before doing this, so commit or stash first or you’ll lose them.
view sourceprint?1.git symbolic-ref HEAD refs/heads/gh-pages2.rm .git/index3.git clean -fdxThen add and commit your site and push to GitHub with git push origin gh-pages. Just as with regular pages, it might take up to 10 minutes for GitHub to pick up on the new site the first time around.
Additional Resources
That should be enough to get you started, but here are a few additional resources that you may want to check out.
- GitHub Pages — The GitHub Pages home page covers the basics here, but also links to some real world examples and covers custom 404 pages.
- Jekyll Wiki — The Jekyll wiki covers more features and configuration options than we’ve taken a look at there. The usage page gives a good overview of everything, and the sites page has a nice collection of sites with source code, which is a good place to look for more examples and inspiration.
- Liquid Templating Language — The Liquid site may be useful if the syntax of the Jekyll templates is new to you.