The basics for getting Kun Li setup.


Kun Li requires Jekyll 3.0. Make sure to run bundle update if you aren’t on the latest version or bundle install if this is your first time installing it.

If you are creating a new Jekyll site using Kun Li following these steps:

  1. Download Kun Li and unzip.
  2. Rename jekyll-theme-skinny-bones-master to something meaningful ie: new-site
  3. Run bundle install to install all Jekyll and all dependencies.
  4. Update _config.yml, add navigation, and add posts/pages. Full details below.

If you want to use Kun Li with an existing Jekyll site follow these steps:

  1. Download Kun Li and unzip.
  2. Rename jekyll-theme-skinny-bones-master to something meaningful ie: new-site
  3. Run bundle install to install all Jekyll and all dependencies.
  4. Add all of your existing posts, pages, and any other content you want to move over.
  5. Update YAML front matter blocks to match names used by Kun Li. Full details below.
  6. Update config.yml, add navigation links. Full details below.

Running Jekyll

The preferred method for running Jekyll is with bundle exec, but if you’re willing to deal with gem conflicts feel free to go cowboy with a jekyll build or jekyll serve.

In some cases, running executables without bundle exec may work, if the executable happens to be installed in your system and does not pull in any gems that conflict with your bundle.

However, this is unreliable and is the source of considerable pain. Even if it looks like it works, it may not work in the future or on another machine.

bundle exec jekyll build

bundle exec jekyll serve


How Kun Li is organized and what the various files are. All posts, layouts, includes, stylesheets, assets, and whatever else is grouped nicely under the root folder. The compiled Jekyll site outputs to _site/.

├── _site                               # compiled site ready to deploy
├── _images                             # unoptimized images
├── _includes                           # reusable blocks for _layouts
├── _layouts
|    ├── archive.html                   # archive listing of a group of posts or collection
|    ├── article.html                   # articles, blog posts, text heavy material layout
|    ├── default.html                   # base
|    ├── research.html                   # base
|    ├── news.html                   # base
|    ├── collaborators.html  
|    ├── recruitment.html  
|    ├── team_building.html  
|    ├── home.html                      # home page
|    └── media.html                     # portfolio, work, media layout
├── _posts                              # posts grouped by category for sanity
├── _sass
|   ├── vendor                          
|   |   ├── bourbon                     # Bourbon mixin library   
|   |   └── neat                        # Neat grid library
|   ├── _animations.scss                # CSS3 animations
|   ├── _badges.scss                    # small badges
|   ├── _bullets.scss                   # visual bullets
|   ├── _buttons.scss                   # buttons
|   ├── _grid-settings.scss             # Neat settings         
|   ├── _helpers.scss                   # site wide helper classes
|   ├── _layout.scss                    # structure and placement, the bulk of the design
|   ├── _mixins.scss                    # custom mixins
|   ├── _notices.scss                   # notice blocks
|   ├── _syntax.scss                    # Pygments.rb syntax highlighting
|   ├── _reset.scss                     # normalize and reset elements
|   ├── _variables.scss                 # global colors and fonts
|   ├── css
|   └── main.scss                       # loads all Sass partials
├── fonts                               # webfonts
├── images                              # images
├── js
|   ├── plugins                         # jQuery plugins
|   ├── vendor                          # vendor scripts that don't get combined with the rest
|   ├── _main.js                        # site scripts and plugin settings go here
|   └── main.min.js                     # concatenated and minified site scripts
├── apple-touch-icon-precomposed.png    # 152x152 px for iOS
├── favicon.ico                      # 32x32 px for browsers
└──                            # homepage content
└── _config.yml                         # Jekyll settings

Site Setup

A quick checklist of the files you’ll want to edit to get up and running.

Site Wide Configuration

_config.yml is your friend. Open it up and personalize it. Most variables are self explanatory but here’s an explanation of each anyways:

Site Title

The title of your site… shocker!

Example title: Kun Li

Site Description

A description of your site. Used in page meta.

Example description: "A lightweight site starter for Jekyll"

Site logo, used mostly as a default image that appears on Twitter Cards if a large feature image isn’t present. If used place a square image around 120 x 120 pixels in /images/.

Example logo: 120x120.gif

sample Twitter Card screenshot
Site logo is used for Twitter Cards when a feature image is not defined for the page.

Site Teaser Image

Default teaser image used for posts and pages that do not have one assigned. This image shows up in the archive grid module. It can have whatever dimensions you want, I’ve found that an image with rectangular proportions work nicely. Like the site logo, place in /images/.

Example teaser: 400x250.gif

Site URL

Used to generate absolute URLs in sitemap.xml, atom.xml, and for generating canonical URLs in <head>. When developing locally either comment this out or use something like http://localhost:4000 so all assets load properly. Don’t include a trailing /.


url: http://localhost:4000

Site Locale

The default is en for English. site.locale is used to apply localized text for a few key strings.


The theme supports localized text through a data file for the following text strings:

To update or add other translations edit _data/messages.yml and then set the appropriate locale in _config.yml. For example to switch from English to German replace locale: en with locale: de or locale: de_DE.

Feel free to submit a pull request for additional languages and any other parts of the theme that could be localized.

To set what links appear in the top navigation edit _data/navigation.yml. Use the following format to set the URL, title, teaser image/description (used in off-canvas menu) of each link:

- title: Portfolio
  url: /portfolio/
  excerpt: "Things I’ve designed, illustrated, developed, coded, and whatever."
  image: 300x200.gif

- title: Made Mistakes

To set what links appear in the footer edit _data/footer.yml. Use the following format for each link:

- title: Subscribe
  url: /subscribe/

- title: External Page


Organizing Posts

Create new MarkDown (.md) files in _posts. If you aren’t using categories to organize your posts then don’t worry about this next bit. I like to organize all my posts by a single category and file them under sub-directories beneath _posts. For example if I have post named and it has a category of foo it will have the following path:


Which when processed by jekyll would have a URL of

YAML Front Matter

The only YAML Front Matter required for posts and pages are title and layout, everything else is optional.


Add categories: and assign a single category name for added organization. The theme makes the assumption that posts will only be assigned to one category at a time. You can certainly assign multiple categories but unexpected things may happen with the permalink structure.

I like to group posts by general categories like articles, portfolio, whatever, and using tags to more specific classifications.

Modified Date

If you assign a modified date to a post or page it will override the published date and appear in the page footer with the following format Updated August 27, 2014. It’s also used as metadata to give search engines another piece of info about your content.

I like to use this Sublime Text plugin to insert the current date after I’ve updated a post, but you can do it manually to. It should follow the same date format used by Jekyll when naming posts: YYYY-MM-DD.

modified: 2014-08-27
modified: 2014-08-27T11:57:41-04:00 # more verbose, also acceptable


Here you can define the various images assigned to posts and pages.

A good rule of thumb is to keep feature images nice and wide so you don’t push the body text too far down. An image cropped around around 1024 x 256 pixels will keep file size down with an acceptable resolution for most devices without bloating your site. If you want to level-up your site I’d suggest looking at the Jekyll Picture Tag plugin1 to make them responsive.

The post and page layouts make the assumption that the feature images live in the images/ folder. To add a feature image to a post or page just include the filename in the front matter like so.

  feature: feature-image-filename.jpg

To add attribution to a feature image use the following YAML front matter on posts or pages. Image credits appear directly below the feature image with a link back to the original source (if supplied).

  feature: feature-image-filename.jpg
  credit: Michael Rose #name of the person or site you want to credit
  creditlink: #url to their site or licensing
Teasers Images

Teaser images appear on archive pages in the post grid and are also used in the off-canvas menu. If you don’t assign a teaser image for a specific post or page, the default one will be used. The default image can be set in _config.yml under site wide configuration teaser: 400x250.gif. Teaser images should be roughly 400 x 250 pixels to scale comfortably across screen sizes.

teaser image screenshot
Images outlined in red show how teasers typically display

Similar to feature images you don’t want to go crazy and use large high resolution assets for your teasers. Keep in mind performance and balance accordingly.

To assign a teaser image on a post use the following YAML:

  teaser: 400x250.gif
  feature: feature-image-filename.jpg
  credit: Michael Rose #name of the person or site you want to credit
  creditlink: #url to their site or licensing

Table of Contents

For longer posts you may find it beneficial to include a table of contents menu. Add {% include toc.html %} where you’d like the TOC to appear and Kramdown will take care of the rest by converting all headlines to list of links.

If you need to alter the Overview headline text that appears at the top of the list, you can do so by editing _data/messages.yml.

Google AdSense

To use Google Ads on your site create a Google AdSense account and then add your ad-client and ad-slot variables to _config.yml. To show ads on a post/page add ads: true to the YAML Front Matter.

responsive type

Select responsive for ad type, allowing it to display at various sizes. If you’d like to use a different ad network just edit the appropriate HTML and JavaScript found in _includes/advertising.html.

Disqus Comments

Create a Disqus account and change disqus-shortname in _config.yml to the Disqus shortname you just setup. To enable commenting on a post, add the following to its YAML Front Matter:

comments: true

Social sharing links for Twitter, Facebook, and Google+ are included on posts/pages using the article and media layouts by default. To hide them on specific posts or pages add share: false to the YAML Front Matter. If you’d like to use different social networks modify _includes/share-this.html to your liking. Icons are set using Font Awesome.

social sharing links screenshot
Share links appear the below author details block.


Organizing Pages

Maintaining pretty URLs for your site can be handled in two ways when creating new pages.

Place a .md file at the root level and add the appropriate permalink to the YAML Front Matter. For example if you want your About page to live at create a file named / and add permalink: /about/ to its YAML Front Matter.

Or you can create /about/ and omit the YAML permalink. Up to you how you’d like to organize your pages.

You can also group pages in a _pages folder similiar to _posts if you follow this short guide.


Create an archive page for each category or section of your site that you want to list a collection of posts. On these pages you’ll want to use the archive layout and use a variation of the following for the page’s content changing foo to the appropriate category you want to list posts from.

<div class="tiles">
{% for post in %}
  {% include post-grid.html %}
{% endfor %}
</div><!-- /.tiles -->

If you’d prefer a less visual list of posts use {% include post-list.html %} instead of the post-grid.html _include.

Adding New Content

Posts are stored in the _posts directory and named according to the YEAR-MONTH-DAY-title.MARKUP format as per the usual.

To streamline the creation of posts and pages, Jekyll::Compose and Octopress are great plugins you can install to automate this process.


Found a bug or aren’t quite sure how something works? By all means submit an issue on GitHub. For straight forward bug fixes feel free to submit pull requests.

Kun Li was built predominately as a framework for my own site. My intention was never to make it all things for all people. So please keep that in mind before submitting new features or enhancements. If you’ve used any of my Jekyll themes I think it’s pretty clear what I like and what I try to avoid. When in doubt ask before wasting your time on a feature that won’t get merged in.


This theme is free and open source software, distributed under the MIT License. So feel free to use this Jekyll theme on your site without linking back to me or including a disclaimer.

  1. If you’re using GitHub Pages to host your site be aware that plugins are disabled. You’ll need to build your site locally and then manually deploy if you want to use this sweet plugin.