GitHub Pages & Jekyll

First, a good book: Http://git-scm.com/book/zh/v1, is said to read the first 4 chapters of this book will use GitHub most of the functions of

Then go to the topic

Original address: http://www.ruanyifeng.com/blog/2012/08/blogging_with_jekyll.html

Build a free, unlimited-Flow blog----GitHub pages and Jekyll Getting Started

Nanyi

Date: August 25, 2012

Those who like to write blog, will experience three stages.

The first stage, just contact blog, feel very fresh, try to choose a free space to write.

The second stage, found that the free space limit too much, buy their own domain name and space, build independent blog.

The third stage, feel that the management of the independent blog is too troublesome, it is best to retain control of the premise, let others to tube, their own only responsible for writing articles.

Most bloggers are stuck in the first and second stages because the third phase is not easy to reach: It's hard to find bow down, the person willing to manage the server for you.

But two years ago, things changed, and some programmers started blogging on the GitHub site. They both have absolute control and enjoy the convenience of GitHub----whenever and wherever they submit a commit to the host, they can post new articles. Even better, it's all free, and GitHub offers unlimited traffic, with the ideal speed of access around the world.

Today, I'll show you how to build a blog on GitHub, where you can learn about GitHub's pages and the basic usage of Jekyll software. More importantly, you will experience a new way of building a website.

What is Github Pages?

If you know something about programming, you must have heard of GitHub. It claims to be a programmer's Facebook, with a high level of popularity and a host of important projects.

Simply put, it is a code warehouse with versioning capabilities, and each project has a home page that lists the project's source files.

But for a novice, see a lot of source code, will only make people dizzy brain rise, do not know where to start. What he wants to see is a simple and understandable web page that explains what to do at each step. As a result, GitHub has designed the pages feature to allow users to customize the project home page to replace the default source list. So, github pages can be thought of as user-authored static Web pages hosted on GitHub.

GitHub provides templates that allow Web pages to be generated within the site, but also allows users to write their own web pages and upload them. Interestingly, this upload is not a simple upload, but will go through the Jekyll process.

Second, what is Jekyll?

Jekyll (pronunciation/' d?i?k? l/, "Jackel") is a static site generator that generates static files based on the source of the Web page. It provides templates, variables, plug-ins, and so on, so you can actually write an entire Web site.

The whole idea here is obvious. You write a local source code that complies with the Jekyll specification, then upload it to GitHub and build and host the entire site from GitHub.

The benefits of this approach are:

* Free, unlimited traffic.

* Enjoy Git's versioning features without worrying about missing articles.

* You just have to use your favorite editor to write articles, other things do not worry about, are processed by GitHub.

Its disadvantages are:

* There is a certain technical threshold, you have to understand a little git and web development.

* It generates a static web page, adding dynamic features must use external services, such as commenting function can only be used disqus.

* It is not suitable for large web sites, because the database is not used, each run must traverse the entire text file, the larger the site, the longer the build time.

In general, however, it is one of the best options for building small-to-medium blogs or project pages.

A city instances

Below, I'll give you an example of how to build a blog on GitHub, and you can do it step-by-step. For ease of understanding, this blog has only the most basic functions.

Before you build it, you have to have Git installed and have a GitHub account.

The first step is to create the project.

On your computer, create a directory as the main directory for the project. We assume that its name is Jekyll_demo.

$ mkdir Jekyll_demo

Git initializes the directory.

$ CD Jekyll_demo

$ git init

Then, create a branch gh-pages that does not have a parent node. Because GitHub specifies that only the pages in that branch will generate a Web page file.

$ git checkout--orphan gh-pages

All of the following actions are done under this branch.

The second step is to create the settings file.

Under the project root directory, create a text file named _config.yml. It is the Jekyll settings file, we fill in the following content, other settings can be used by default options, specific explanation see the official page.

BaseURL:/jekyll_demo

The directory structure becomes:

/jekyll_demo
|--_config.yml

The third step is to create the template file.

Under the project root, create a _layouts directory to hold the template files.

$ mkdir _layouts

Enter the directory and create a default.html file as the default template for the blog. and fill in the file with the following content.

<! DOCTYPE html>

<meta http-equiv= "Content-type" content= "text/html; Charset=utf-8 "/>

<title>{{Page.title}}</title>

<body>

{Content}}

</body>

Jekyll uses the liquid template language, {{page.title}} to represent the article title, {{content}} for the article content, and more template variables refer to the official documentation.

The directory structure becomes:

/jekyll_demo
|--_config.yml
|--_layouts
| |--default.html

Fourth step, create the article.

Go back to the project root and create a _posts directory to hold blog posts.

$ mkdir _posts

Enter the directory to create the first article. The article is an ordinary text file, the file name is assumed to be 2012-08-25-hello-world.html. (Note that the file name must be in the format "year-month-day-article title. Suffix name". If the page code is in HTML format, the suffix is HTML, and if the markdown format is used, the suffix is md. ）

In the file, fill in the following: (note that there must be no spaces at the beginning of the line)

---
Layout:default
Title: Hello, World
---

<p> my first post </p>

<p>{{page.date | date_to_string}}</p>

The head of each article must have a Yaml file header that is used to set some metadata. It uses three dashes "---", marks the start and end, and each row sets a meta-data. "Layout:default" means that the template for the article uses the default.html file in the _layouts directory; "title: Hello, World", meaning that the title of the article is "Hello, world", if you do not set this value, the title of the embedded file name is used by default, i.e. " Hello world. "

After the Yaml file header, it is the official content of the article, which can use template variables. {{Page.title}} is the "Hello, World" set in the file header, {{page.date}} is the date of the embedded file name (you can also redefine the day variable in the header), "| Date_to_string "means converting the page.date variable into a human-readable format.

The directory structure becomes:

/jekyll_demo
|--_config.yml
|--_layouts
| |--default.html
|--_posts
| |--2012-08-25-hello-world.html

Fifth step, create the first page.

With the article, you also need to have a home page.

Go back to the root directory, create a index.html file, and fill in the following content.

---
Layout:default
Title: My Blog
---

<p> Latest Articles </p>

<ul>

{% for post in site.posts%}

<li>{{post.date | date_to_string}} <a href= "{{Site.baseurl}}{{Post.url}}" >{{Post.title}}</a>< /li>

{% ENDFOR%}

</ul>

Its Yaml file header indicates that the home page uses the default template, titled "My Blog". The first page then uses {% for post in site.posts%}, which means a traversal of all posts. Note here that the Liquid template language stipulates that the output uses two curly braces, and the simple command uses a single layer of curly braces. As for {{Site.baseurl}} is the BaseURL variable set in _CONFIG.YML.

The directory structure becomes:

/jekyll_demo
|--_config.yml
|--_layouts
| |--default.html
|--_posts
| |--2012-08-25-hello-world.html
|--index.html

Sixth step, publish the content.

Now, this simple blog can be published. Add all the content to your local git repository first.

$ git Add.

$ git commit-m "first post"

Then, go to GitHub's website and create a library named Jekyll_demo on the site. Next, push the local content to the library you just created on GitHub. Note that the username in the command below will be replaced by your username.

$ git Remote add Origin https://github.com/username/jekyll_demo.git

$ GIT push origin gh-pages

After uploading the success, wait 10 minutes or so, visit http://username.github.com/jekyll_demo/can see the blog has been generated (username replaced by your username).

Home:

Article page:

Seventh step, bind the domain name.

If you do not want to use http://username.github.com/jekyll_demo/this domain name, can be replaced by your own domain name.

The specific method is to create a new text file named CNAME under the root directory of repo, which writes the domain name you want to bind to, such as example.com or xxx.example.com.

If you are binding a top-level domain, DNS creates a new a record, pointing to 204.232.175.78. If you are binding a level two domain name, then DNS will create a new CNAME record, pointing to username.github.com (please replace username with your user name). Also, don't forget to change the BaseURL in the _config.yml file to the root directory "/".

At this point, the simplest blog even if the building is complete. For further improvement, please refer to the Jekyll Founder's sample library, as well as other blogs built with Jekyll.

(End

GitHub Pages & Jekyll