How to write post in github pages

[updated 2015.10.30] The following way is deprecated, and octopress way is prefered. But the To make the post searchable by Google part is still in use.

Contents:

To add a new post
To add a new “category” or “tag”
To enable code highlight
To make the post searchable by Google
Some tips for markdown grammar

The first two sections are only for my project pages (gh-pages) GitBlogs, and currently in cotopress blog, we have other new simpler ways to do these things. See Migrate Blog to Octopress.

Description

This post is not for how to deploy the environment of writing posts in github pages, but how to use the environment you deployed before.

Assuming that you have deployed the following tools:

In Local:

Jekyll
Git
MarkdownPad

In Remote:

github repo

To add a new post

git clone *https://github.com/hongchaozhang/GitBlogs.git*
go to gh-pages branch
open _post folder, add a new md file named like this: 2015-05-20-How-to-write-post-in-github-pages.md. Notice: DO NOT leave any space in the file title.
use MarkdownPad in windows or Macdown in mac to open the md file you created, and put the yaml title on the top as follows (Note: three dashes at the top and bottom):

---
layout: default
comments: true
category: choose only one from /data/categories.yml
tags: [tag1, tag2, …, tagn] choose from /data/tags.yml
title: How to write post in github pages
---
If you don’t have a local MarkdownPad, you can use online tools to edit the md file, like stackedit, a very powerful one. Five star recommended O(∩_∩)O~！
Add the content of the post. For Markdown grammar, refer here for Chinese version.
After complete the md file, you can directly push the md file to github repo, if you believe it has nothing wrong.

For an alternative, you can using your local Jekyll to start a server and test the post you wrote. To do this:

Open cmd window.
Go to you post foler, for me, it is GitBlogs.
Start Jekyll server by running: jekyll serve
Open server address listed in cmd window, for me, it is localhost:4000/GitBlogs

To add a new “category” or “tag”

If we want to add a new tag “java” into our blog, we should:

go to /blog/tag/ folder, and add a new file named “java.md”;
add the following content into the new file:

---
layout: blog_by_tag
tag: java
permalink: /blog/tag/java/
---
go to /_data/ folder, and open tags.yml;
add the following content into tags.yml file (NOTE the indent and spaces):

- slug: java
name: java

For “category”, it is similar.

To enable code highlihgt

official site

Improve Code Highlighting in a Jekyll-based Blog Site

Add syntax highlighter CSS file as css/syntax.css to your site
Load CSS inside of a corresponding layout file (e.g. _layouts/default.html)

<head>
...
<link href="/css/syntax.css" rel="stylesheet">
...
</head>

Wrap your code snippets in posts with {\% highlight objc linenos \%} and {\% endhighlight \%} Liquid tags, Jekyll will (via Pygments highlighter) output color highlighted code based on chosen language scheme (e.g. objc in my case).

There is a problem here: when you select code, the line numbers are also selected. There are two ways to solve this:

add linenos=table instead of linenos in the directive {\% highlight objc linenos \%}. The table may look ugly.
Add the following javascript code into your site (depending on jQuery):

// hide line numbers in code pieces right before we copy the code
$(document).ready(function () {
  $("code").bind("copy", function () {
      var innerHtml = this.innerHTML;
      $(this).find('.lineno').remove();
      var that = this;
      setTimeout(function(){
          $(that).children().remove();
          that.innerHTML = innerHtml;
      },0);
  });
});

To make the post searchable by Google

Refer here.

Google crawls and ranks websites partially based on links to it from other websites. You should consider submitting it to some award websites, show-and-tells, etc to increase the value of the domain.

It can take a few days to a few months to be indexed, depending on several factors. It’s recommended that you use the submit URL tool, which may help speed up this process.

I tried the submit URL tool, and after hald day, my blogs can be searched in google. But you should use exactly the same words in your post to search, or your post may be very behind, as the value of your domain is very low.

Some tips for markdown grammar

insert an image

To insert the image, just use the path under the base url, for me, it is /GitBlogs/images/.png, for example

![image annotation](/GitBlogs/images/001_ios_frameworks.png)

[updated 2015.09.13] The above is for my project pages (gh-pages) GitBlogs, and for octopress, the base url is /, and only images/<image_name>.png is needed.