Jekyll Poole Lanyon Blog Building

The most important reference is How I Created a Beautiful and Minimal Blog Using Jekyll, Github Pages, and poole, Lanyon and Poole on Github.

Procedure

1 Install git command
$ sudo apt-get install git
$ git config --global ... For configuration commands refer to official website on "Set up Git".

Mainly two commands:

1. git config --global user.name "YOUR NAME"
2. git config --global user.email "YOUR EMAIL". You can hide your email address by Keeping your email address private.

2 Create user pages
Create a empty repository called username.github.com on Github web without README file.
3 Ubuntu Command lines
Copy Lanyon locally.
$ git clone https://github.com/poole/lanyon.git username.github.com
Enter the new cloned repository.
$ cd username.github.com
Set remote repository to sync later on.
$ git remote set-url origin https://github.com/username/username.github.com.git
Push locall repository to remote.
$ git push origin master
4 Visit username.github.io
What you see it not yours, all the contents are from Lanyon. We need to modify the contents for our own use. We should firstly validate the modification before push to remote repository. Jekyll can do that validation.
5 Jekyll
For installation, refer to Install Jekyll 2 on Ubuntu 14.04 and Official site.

1. sudo apt-get install ruby ruby-dev.

   ruby-dev must be installed otherwise see Error Installing Jekyll - Native Extension Build.

   The reference links require installing of rubygems, which is not necessary now. The rubygems package now is a purly virtual package and part of the real package ruby. See can not install rubygems1.9.1 on Maverick Meerkat rc. You can test it by command dpkg -L ruby. It shows gem is already installed by the ruby package.

2. sudo gem install jekyll. This might take a while.
3. sudo apt-get install nodejs There is an issue that causes Jekyll to require a JavaScript runtime even if it will not be used. Installing nodejs helps solve the issue
4. jekyll -v

Jekyll comes with a built-in development server that will allow you to preview what the generated site will look like in your browser locally by http://localhost:4000. You can try now:

• Run $ jekyll server/serve/s in username.github.com directory
• Open browser enter localhost:4000.

There you go! You can see a local copy of the repository. What you need to do now is to modify the contents locally for personal use.

6 Modification

The first is to modify the _config.yml configuration file such as contact info, blog title, etc. The url varialble in _config.yml, I found it not useful. Remove it.

For baseurl setting, refer to 4. Serving it up section.

1. If you're using a custom domain name, leave it as /. Then modify the CNAME file to point to new domain www.fangxiang.tk.
2. If you're not using a custom domain name, modify the baseurl in _config.yml to point to your GitHub Pages URL. Example: for a repo at github.com/username/poole, use http://username.github.io/poole/. Be sure to include the trailing slash.

Sidebar "Download" and "Github Project" items does not work. Because custom variable site.github.repo is not defined in _config.yml. The site.github.repo is used in _include/sidebar.html. Just add two lines in _config.yml as follows. Pay attention to the indent of the second line.

github:
  repo:	https://github.com/outsinre/outsinre.github.com

Though the problem was solved, I don't need the two sidebar items. So I removed them from _config.yml. Correspondingly, the lines in _include/sidebar.html should also be removed.

Disqus comments. Firsly, create a file comments.html and add two lines:

{% if page.comments %}

{% endif %}

Then paste the DISQUS universal code between the two lines. The comments.html should be placed under _include folder. After that, in _layout/post.html, _layout/page.html, _layout/default.html files, add a line {% include comments.html %}. Also in the very front add comments: true.

What is DISQUS universal code? First, in DISQUS setup, add a site identifier, i.e. jekylldq. Then, QISQUS will generate the universal code automatically for you. Lastly, just copy and paste it.

Archive page added based on the reference at the beginning.

Subscribe page added by modifying _include/sidebar.html.

znhoo.css added in public/css/znhoo.css, especially for blog text-align: justify.

Site icon changed referring to icons. Check the file _include/head.html for where is icon defined.

read more…* to only display the first paragraph of a post. Only need to modify the index.html file. The original is to display the post content completely:

{{ post.content }}

but now replaced by:

{{ post.excerpt | remove: '<p>' | remove: '</p>' }}

{% if post.content.size > 500 %}
  <br /><br /><a href="{{ post.url }}">Read more...</a>
{% endif %}

code line numbers refer to Improve Code Highlighting in a Jekyll-based Blog Site. Especially pay due attention to its comments. How? Add several lines for public/css/syntax.css:

1
2
3
4
5
6
7
8
9
10
/* display code line number; the line number is displayed aside from the code separated by a vertical line */
.highlight .lineno { color: #ccc; display:inline-block; padding: 0 5px; border-right:1px solid #ccc; }
.highlight pre code { display: block; white-space: pre; overflow-x: auto; word-wrap: normal; }

/* exclude line numbers from copy-paste user operations; if you copy the code, the line numbers are also copied, so this line is to disable line number copy */
.highlight .lineno {-webkit-user-select: none;-moz-user-select: none; -o-user-select: none;}

/* override text selection hightlighting for line numbers; although the above line disables line number copy, but when you select the code, line numbers are also selected which looks ugly; the transparent color will help erase this */
.lineno::-moz-selection {background-color: transparent;} /* Mozilla specific */
.lineno::selection {background-color: transparent;} /* Other major browsers */

baseurl in _config.yml file. Please refer to GitHub Pages. Basically, pay attention to the leading slash and trailing slash issue when writing post. It is better to include the site.baseurl when accessing files. Don't use /. Because the blog might be migrated to some other places or to a project github pages in the future, which causes compatibility issue. For example, to include an image in post:

1
<img src="{{ site.baseurl }}assets/hknight.jpg">

If you replace: ` {{ site.baseurl }} ` with /, it is fine with user github page. But if the blog is migrated to project github page, then it does not work. You have to change / to /project-name/ in your post. If you have many such posts, it is a big trouble. However, site.baseurl works fine. The only place you need to change is the _config.yml file.

fonts setting. Firstly, Open layman.css and search for font-family, I removed all the fonts related to PT like PT Sans or PT Serif. Then commented out the line:

1
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Serif:400,400italic,700%7CPT+Sans:400">

from head.html.

Setup

Some fun facts about the setup of Poole project include:

• Built for Jekyll
• Developed on GitHub and hosted for free on GitHub Pages
• Coded with Sublime Text 2, an amazing code editor
• Designed and developed while listening to music like Blood Bros Trilogy

Have questions or suggestions? Contact Poole author on Twitter.

Thanks for reading!