Jekyll's Ferrari

Octopress 3 Documentation (Book Edition)

by Brandon Mathis et al

An obsessively designed toolkit for writing and deploying Jekyll blogs

Contents

Getting Started
- Welcome
Tags
- Image
- Codeblock
- Video
- Pullquote
- Quote
- Content For
- Render
- Markdown
Goodies
- Social
- Feeds
- Linkblog
Themes
- Genesis
Miscellaneous
- Multilingual
- Date Format
- Filters

Preface

Note: The book edition is still an early release and a work-in-progess.

This is the documentation (mostly READMEs) for Octopress 3 - a toolkit for the Jekyll static site builder / generator - reformatted in a single-page book edition.

See the source repo for how the book gets auto-built with "plain" Jekyll - of course - and hosted on GitHub Pages.

Questions? Comments? Send them to the Jekyll Talk forum post titled Octopress 3 (Jekyll's Ferrari) Docu Reformatted as a Single Page in Black 'n' White (Book Version).

Onwards.

Acknowledgments

Thanks to Brandon Mathis and all Octopress contributors for making it all possible.

Part 1 - Getting Started

Chapter 1.1 - Welcome

Octopress is an obsessively designed toolkit for writing and deploying Jekyll blogs. Pretty sweet, huh?

Installation

Install Octopress manually:

$ gem install octopress

Or if you use Bundler, add this line to your Gemfile:

gem 'octopress', '~> 3.0'

And then run:

$ bundle

New to bundler? Run gem install bundler then create a file named Gemfile in your site’s root directory with the following content:

source 'https://rubygems.org'

gem 'octopress', '~> 3.0'

Run bundle to install the gems specified in your Gemfile.

Configuration

Octopress reads its configurations from _config.yml. Here’s what the configuration looks like by default.

# Default extension for new posts and pages
post_ext: markdown
page_ext: html

# Default templates for posts and pages
# Found in _templates/
post_layout: post
page_layout: page

# Format titles with titlecase?
titlecase: true

# Change default template file (in _templates/)
post_template: post
page_template: page
draft_template: draft

Octopress CLI Commands

Here are the subcommands for Octopress.

init <PATH>         # Adds Octopress scaffolding to your site
new <PATH>          # Like `jekyll new` + `octopress init`
new post <TITLE>    # Add a new post to your site
new page <PATH>     # Add a new page to your site
new draft <TITLE>   # Add a new draft post to your site
publish <POST>      # Publish a draft from _drafts to _posts
unpublish <POST>    # Search for a post and convert it into a draft
isolate [POST]      # Stash all posts but the one you're working on for a faster build
integrate           # Restores all posts, doing the opposite of the isolate command
deploy              # deploy your site via S3, Rsync, or to GitHub pages.

Run octopress --help to list sub commands and octopress <subcommand> --help to learn more about any subcommand and see its options.

Init

$ octopress init <PATH> [options]

This will copy Octopress’s scaffolding into the specified directory. Use the --force option to overwrite existing files. The scaffolding is pretty simple:

_templates/
  draft
  post
  page

New Post

This automates the creation of a new post.

$ octopress new post "My Title"

This will create a new file at _posts/YYYY-MM-DD-my-title.markdown with the following YAML front-matter already added.

layout: post
title: "My Title"
date: YYYY-MM-DDTHH:MM:SS-00:00

Command options

Option	Description
`--template PATH`	Use a template from
`--date DATE`	The date for the post. Should be parseable by Time#parse
`--slug SLUG`	Slug for the new post.
`--dir DIR`	Create post at _posts/DIR/.
`--force`	Overwrite existing file.

New Page

Creating a new page is easy, you can use the default file name extension (.html), pass a specific extension, or end with a / to create an index.html document.

$ octopress new page some-page           # ./some-page.html
$ octopress new page about.md            # ./about.md
$ octopress new page docs/               # ./docs/index.html

If you are working with collections, you might add a page like this:

$ octopress new page _legal/terms        # ./_legal/terms.html

After the page is created, Octopress will tell you how to configure this new collection.

Command options

Option	Description
`--template PATH`	Use a template from
`--title TITLE`	The title of the new page
`--date DATE`	The date for the page. Should be parseable by Time#parse
`--force`	Overwrite existing file.

Note: The default page template doesn’t expect a date. If you want to add dates to your pages, consider adding date: to the default template _templates/page, or create a new template to use for dated pages. Otherwise, you will have the --date option to add a date to a page.

New Draft

This will create a new post in your _drafts directory.

$ octopress new draft "My Title"

Option	Description
`--template PATH`	Use a template from
`--date DATE`	The date for the draft. Should be parseable by Time#parse (defaults to Time.now)
`--slug SLUG`	The slug for the new post.
`--force`	Overwrite existing file.

Publish a draft

Use the publish command to publish a draft to the _posts folder. This will also rename the file with the proper date format.

$ octopress publish _drafts/some-cool-post.md
$ octopress publish cool

In the first example, a draft is published using the path. The publish command can also search for a post by filename. The second command would work the same as the first. If other drafts match your search, you will be prompted to select them from a menu. This is often much faster than typing out the full path.

Option	Description
`--date DATE`	The date for the post. Should be parseable by Time#parse
`--slug SLUG`	Change the slug for the new post.
`--dir DIR`	Create post at _posts/DIR/.
`--force`	Overwrite existing file.

When publishing a draft, the new post will use the draft’s date. Pass the option --date now to the publish command to set the new post date from your system clock. As usual, you can pass any compatible date string as well.

Unpublish a post

Use the unpublish command to move a post to the _drafts directory, renaming the file according to the drafts convention.

$ octopress unpublish _posts/2015-01-10-some-post.md
$ octopress unpublish some post

Just like the publish command, you can either pass a path or a search string to match the file name. If more than one match is found, you will be prompted to select from a menu of posts.

Templates for Posts and pages

Octopress post and page templates look like this.

---
layout: {}
title: 
---

Dates get automatically added to a template for posts, and for pages if a –date option is set.

You can add to the YAML front matter, add content below and even use liquid tags and filters from your site’s plugins. There are a handful of local variables you can use when working with templates.

Variable	Description
`date`	The date (if set) or Time.now.iso8601
`title`	The title of the page (if set)
`slug`	The title in slug form
`ymd`	The date string, YYYY-MM-DD format
`year`	The date’s year
`month`	The date’s month, MM
`day`	The date’s day, DD

By default Octopress has templates for pages, posts and drafts. You can change them or create new ones for different types of content. To create linkposts template, add a file at _templates/linkpost, such as:

---
title: 
external-url: 
---

Then you can use it with a new post like this:

$ octopress new post "Some title" --template linkpost
$ octopress new post "Some title" -tm _templates/linkpost

In the second example, I’m passing the full template file path. This way I can use my shell’s tab to auto-complete feature.

When creating templates, file name extensions are unnecessary since the files are just plain text anyway.

Isolate

The isolate command will allow you to stash posts in _posts/_exile where they will be ignored by Jekyll during the build process. Run octopress integrate to restore all exiled posts. This can be helpful if you have a very large site and you want to quickly preview a build for a single post or page.

$ octopress isolate                                # Move all posts
$ octopress isolate _posts/2014-10-11-kittens.md   # Move post at path
$ octopress isolate kittens                        # Move post matching search

In the third example, if multiple posts match the search a prompt will ask you to select a post from a menu.

Deploying your site

The Octopress gem comes with octopress-deploy which allows you to easily deploy your site with Rsync, on S3 or Cloudfront, to GitHub pages, or other Git based deployment hosting platforms.

Once you’ve built your site (with jekyll build) you can deploy it like this:

$ octopress deploy

This reads a _deploy.yml configuration and deploys your site. Read below to learn how Octopress can generate a deployment configuration file for you.

Note: The _deploy.yml is processed through ERB, which makes it easy to load configurations from environment variables.

Deploy has a few commands you should know.

Commands	Description
`octopress deploy`	Deploy your site (based on the `_deploy.yml` configuration)
`octopress deploy init <METHOD> [options]`	Generate a config file for the deployment method. (git, s3, rsync)
`octopress deploy pull [DIR]`	Pull down your site into a local directory.
`octopress deploy add-bucket <NAME>`	(S3 only) Add a bucket using your configured S3 credentials.

Generate Deployment configuration

Remember to add your configuration to .gitignore to be sure you never commit sensitive information to your repository.

Octopress can generate a deployment configuration file for you using the octopress deploy init command.

$ octopress deploy init s3
$ octopress deploy init rsync
$ octopress deploy init git git@github.com:user/project

This will generate a _deploy.yml file in your current directory which you can edit to add any necessary configuration.

If you like, you can pass configurations as command line options. To see specific options for any method, add the --help flag. For example to see the options for configuring S3:

$ octopress deploy init s3 --help

If you want to publish your site to a staging server, you can create a second configuration. For example, to setup rsync for a staging site, you’d do this.

$ octopress deploy init rsync --config _staging.yml

After modifying the configuration file, you can deploy your site to it like this:

$ octopress deploy --config _staging.yml

Git Deployment Configuration

Only git_url is required. Other options will default as shown below.

Config	Description	Default
`method`	Deployment method, in this case use ‘git’
`site_dir`	Path to static site files	_site
`git_url`	Url for remote git repository
`git_branch`	Deployment branch for git repository	master
`deploy_dir`	Directory where deployment files are staged	.deploy
`remote`	Name of git remote	deploy

Rsync Deployment Configuration

Config	Description	Default
`method`	Deployment method, in this case use ‘rsync’
`site_dir`	Path to static site files	_site
`user`	ssh user, e.g user@host.com
`port`	ssh port	22
`remote_path`	Remote destination’s document root
`exclude_from`	Path to a file containing rsync exclusions
`exclude`	Inline list of rsync exclusions
`include_from`	Path to a file containing rsync inclusions
`include`	Inline list of inclusions to override exclusions
`delete`	Delete files in destination not found in source	false

You can rsync to a local directory by configuring remote_path and leaving off user and port.

Amazon S3 Deployment Configuration

To deploy with Amazon S3 you will need to install the aws-sdk-v1 gem.

Important: when using S3, you must add your _deploy.yml to your .gitignore to prevent accidentally sharing account access information.

Config	Description	Default
`method`	Deployment method, in this case use ‘s3’
`site_dir`	Path to static site files	_site
`bucket_name`	S3 bucket name
`access_key_id`	AWS access key
`secret_access_key`	AWS secret key
`distribution_id`	[optional] AWS CloudFront distribution id
`remote_path`	Directory files should be synced to.	/
`verbose`	[optional] Display all file actions during deploy.	false
`incremental`	[optional] Incremental deploy (only updated files)	false
`region`	[optional] Region for your AWS bucket	us-east-1
`delete`	Delete files in `remote_path` not found in `site_dir`	false
`headers`	Set headers for matched files	[]

If you choose a bucket which doesn’t yet exist, Octopress Deploy will offer to create it for you, and offer to configure it as a static website.

If you configure Octopress to delete files, all files found in the remote_path on S3 bucket will be removed unless they match local site files. If remote_path is a subdirectory, only files in that subdirectory will be evaluated for deletion.

You can also set up your configuration to read your AWS credentials from your environment variables using ERB like this:

access_key_id: <%= ENV['AWS_ACCESS_KEY'] %>
secret_access_key: <%= ENV['AWS_SECRET_KEY'] %>

S3 Headers

You can create an array of header configs to set expiration, content and cache settings for any paths matching the filename.

Header Config	Description	Default
`filename`	A regex or a substring of the file to match
`site_dir`	An http date or a number of years or days from now
`content_type`	A string which is passed through to the headers
`content_encoding`	A string which is passed through to the headers
`cache_control`	A string which is passed through to the headers

Here is how you might set expiration and cache controls for CSS and Javascript files.

headers:
  - filename: '^assets.*\.js$'
    expires: '+3 years'
    cache_control: 'max-age=94608000'
    content_type: 'application/javascript'
  - filename: '^assets.*\.css$'
    expires: '+3 years'
    cache_control: 'max-age=94608000'
    content_type: 'text/css'

AWS config via ENV

If you prefer, you can store AWS access credentials in environment variables instead of a configuration file.

Config	ENV var
`access_key_id`	AWS_ACCESS_KEY_ID
`secret_access_key`	AWS_SECRET_ACCESS_KEY

Note: configurations in _deploy.yml will override environment variables so be sure to remove those if you decide to use environment variables.

Pull down your site

With the pull command, you can pull your site down into a local directory.

$ octopress deploy pull [DIR]

Mainly you’d do this if you’re troubleshooting deployment and you want to see if it’s working how you expected.

Part 2 - Tags

Chapter 2.1 - Image

A nice image tag for Jekyll sites.

Installation

Using Bundler

Add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-image-tag'
end

Then install the gem with Bundler

$ bundle

Manual Installation

$ gem install octopress-image-tag

Then add the gem to your Jekyll configuration.

gems:
  -octopress-image-tag

Usage


{% img [class names] url [width [height]] "[alt text]" [title:""] %}

Examples:


{% img /images/ninja.png "Ninja Attack!" %}
{% img left half http://site.com/images/ninja.png title:"Hidden Ninja" %}
{% img {{ site.cdn }}/images/ninja.png 150px 150px %}

Output:

<img src="/images/ninja.png" alt="Ninja Attack!" >
<img class="left half" src="http://site.com/images/ninja.png" alt="Hidden Ninja" title="Hidden Ninja" >
<img src="http://some.cdn.io/images/ninja.png" width="150px" height="150px" alt="Ninja in the shadows" title="Hidden Ninja">

Chapter 2.2 - Codeblock

Write beautiful code snippets within any template.

Installation

Using Bundler

Add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-codeblock'
end

Then install the gem with Bundler

$ bundle

Manual Installation

$ gem install octopress-codeblock

Then add the gem to your Jekyll configuration.

gems:
  - octopress-codeblock

Usage

{% codeblock [options] %}
[lines of code code]
{% endcodeblock %}

Options

Note that order does not matter.

Options	Example	Description
`lang`	`lang:ruby`	Used by the syntax highlighter. Passing ‘plain’ disables highlighting.
`title`	`title:"Figure 1.A"`	Add a figcaption title to your code block.
`link_text`	`link_text:"Download"`	Text for the link, default: `"link"`.
`linenos`	`linenos:false`	Disable line numbering.
`start`	`start:5`	Start the line numbering at the given value.
`mark`	`mark:1-4,8`	Highlight lines of code. This example marks lines 1,2,3,4 and 8
`class`	`class:"css example"`	Add CSS class names to the code `<figure>` element

Example


{% codeblock lang:ruby title:"Check if a number is prime" mark:3 %}
class Fixnum
  def prime?
    ('1' * self) !~ /^1?$|^(11+?)\1+$/
  end
end
{% endcodeblock %}

Demo

class Fixnum
  def prime?
    ('1' * self) !~ /^1?$|^(11+?)\1+$/
  end
end

Chapter 2.3 - Video

Easy HTML5 video tags for Jekyll sites.

Installation

Using Bundler

Add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-video-tag'
end

Then install the gem with Bundler

$ bundle

Manual Installation

$ gem install octopress-video-tag

Then add the gem to your Jekyll configuration.

gems:
  -octopress-video-tag

Syntax

Creating a proper HTML5 video tag couldn’t be simpler.

{% video urls [class names] [width height] [preload:auto|metadata|none] %}

URLs

URLs must include a protocol http or https or begin with a /. URLs for videos should point to mp4, ogv, and/or webm. Adding a url to an image will set that image as the video’s poster frame.

Preload

Preload has three settings:

auto - The Video should start downloading when the page is loaded.
metadata - Only the videos metadata is downloaded when the page is loaded.
none - The video will only be downloaded when the viewer clicks.

This plugin defaults to preloading metadata. This uses minimal bandwidth while still allowing the video to start playing quickly.

Click to play

Each video is embedded with a minuscule bit of javascript which plays videos when they are clicked. If you’d prefer to disable this feature, set click_to_play_video: false in your site’s configuration.

Examples:


{% video {{ site.cdn }}/videos/clouds.mp4 %}
{% video featured wide /images/clouds.jpg /videos/clouds.mp4 /videos/clouds.webm /videos/clouds.ogv 1080px 608px preload:auto %}

This would output the following HTML

<video controls preload='metadata' onclick='(function(el){ if(el.paused) el.play(); else el.pause() })(this)'>
  <source src='https://cdn.com/video/clouds.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
</video>

<video class='featured wide' controls poster='/images/clouds.jpg' width='1080px' height='608px' preload='auto'
  onclick='(function(el){ if(el.paused) el.play(); else el.pause() })(this)'>
  <source src='/videos/clouds.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
  <source src='/videos/clouds.webm' type='video/webm; codecs="vp8, vorbis"'>
  <source src='/videos/clouds.ogv' type='video/ogg; codecs="theora, vorbis"'>
</video>

Chapter 2.4 - Pullquote

Elegant pull-quotes for Jekyll sites.

Installation

Using Bundler

Add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-pullquote-tag'
end

Then install the gem with Bundler

$ bundle

Manual Installation

$ gem install octopress-pullquote-tag

Then add the gem to your Jekyll configuration.

gems:
  -octopress-pullquote-tag

Usage

Surround the paragraph you want to quote from with a {% pullquote %} tag.
Surround the quote you want to use with {" and "}.

For example:


{% pullquote %}
When writing long-form posts, I find it helpful to include pull-quotes, which help
those scanning a post discern whether or not a post is helpful. It is important to 
note, {" pull-quotes are merely visual in presentation and should not appear twice in the text. "} That 
is why it is preferred to use a CSS only technique for styling pull-quotes.
{% endpullquote %}

This will output the following:

<p><span data-pullquote="pullquotes are merely visual in presentation and should not appear twice in the text."></span>
When writing long-form posts, I find it helpful to include pull-quotes, which help
those scanning a post discern whether or not a post is helpful. It is important to 
note, pull-quotes are merely visual in presentation and should not appear twice in the text. That 
is why it is preferred to use a CSS only technique for styling pull-quotes.</p>

Styling & Classnames

This plugin does not currently ship with its own CSS for styling. Octopress themes will have styling for this or you may look to Maykel Loomans for inspiration.

By default pull-quotes will be given the classname pullquote-right. For center or left aligned pull quotes, add the alignment to the tag like this.


{% pullquote %}        #=> class='pullquote-right'
{% pullquote left %}   #=> class='pullquote-left'
{% pullquote center %} #=> class='pullquote-center'

Any other text added to the pull-quote tag will be added as a classname too.


{% pullquote big %}              #=> class='pullquote-right big'
{% pullquote left highlight %}   #=> class='pullquote-left highlight'

Chapter 2.5 - Quote

Easy HTML5 blockquotes for Jekyll sites.

Installation

Using Bundler

Add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-quote-tag'
end

Then install the gem with Bundler

$ bundle

Manual Installation

$ gem install octopress-quote-tag

Then add the gem to your Jekyll configuration.

gems:
  -octopress-quote-tag

Usage


{% quote [options] %}
Some great quote
{% endquote %}

Options:

option	default	description
author	nil	String: Quote author
title	nil	String: Title of work cited
url	nil	String: Link to work

Example


{% quote author:"Bob McAwesome" url:http://example.com title:"Great Wisdom" %} 
Never pet a burning dog.
{% endquote %}

<figure class='quote'>
  <blockquote>
    <p>Some great quote</p>
  </blockquote>
  <figcaption class='quote-source'>
    <span class='quote-author'>Bob McAwesome</span>
    <cite class='quote-title'><a href='http://example.com'>Great Wisdom</a></cite>
  </figcaption>
</figure>

Why?

In Markdown Blockquotes are simple but attribution isn’t. Also, writing the semantic HTML is tricky and easy to forget.

> Some cool quote

# becomes:

<blockquote>
  <p>Some cool quote</p>
</blockquote>

But what if you want to cite an author or a source?

> Some cool quote
> - Bob McAwesome

# becomes:

<blockquote>
  <p>Some cool quote
- Bob McAwesome</p>
</blockquote>

Which doesn’t work at all since a browser will see it as:

Some cool quote - Bob McAwesome

And now you know.

Chapter 2.6 - Content For

Add content_for and yield tags to Jekyll with conditional rendering and in-line filters.

Installation

If you’re using bundler add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-content-for'
end

Then install the gem with Bundler

$ bundle

To install manually without bundler:

$ gem install octopress-content-for

Then add the gem to your Jekyll configuration.

gems:
  -octopress-content-for

Usage

Use it like a typical content_for tag.


{% content_for awesome_content %}
some content
{% endcontent_for %}

{% yield awesome_content %}  //=> some content

Use in-line filters.


{% yield awesome_content | upcase %}  //=> SOME CONTENT

Use conditional rendering in both content_for and yield tags.


{% content_for footer unless page.footer == false %}
Footer!
{% endcontent_for %}

{% yield footer if page.footer %}

Chapter 2.7 - Render

Embed code snippets from the file system in your Jekyll site.

Installation

Using Bundler

Add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-render-code'
end

Then install the gem with Bundler

$ bundle

Manual Installation

$ gem install octopress-render-code

Then add the gem to your Jekyll configuration.

gems:
  -octopress-render-code

Usage

{% render_code <FILE> [options] %}

Configuration

In your site’s configuration, you can set the directory for embedded code samples.

code_dir: code-examples

The default directory is ‘downloads/code’

Options

Note that order does not matter.

Options	Example	Description
`lang`	`lang:ruby`	Defaults to guessing from file name extension.
`title`	`title:"Figure 1.A"`	Add a figcaption title to your code block.
`link_text`	`link_text:"Download"`	Text for the link, default: `"Raw code"`.
`linenos`	`lineos:false`	Disable line numbering.
`start`	`start:5`	Start embedding the script from the 5th line number.
`end`	`end:15`	Stop embedding the script after 15th line number.
`range`	`range:5-15`	Embed lines 5-15 of the script.
`mark`	`mark:5-7,10`	Highlight lines of code. This example marks lines 5,6,7 and 10.
`class`	`class:"solution"`	Add CSS class name(s) to the code `<figure>` element.

Example

Given the existence of a file


{% render figure-1-a.js title:"Figure A: A Simple AJAX Request." mark:5-8

This will

Embed and highlight a file at [site_source]/downloads/code/figure-1-a.js
Give it a figcaption “Figure A: A Simple AJAX Request
Visually mark lines 5,6,7, and 8.

Chapter 2.8 - Markdown

Why? Because you should be able to:

Write markdown anywhere.
Process {% include %} tags with markdown.

Installation

If you’re using bundler add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-markdown-tag'
end

Then install the gem with Bundler

$ bundle

Or install it manually:

$ gem install octopress-markdown-tag

Then add the gem to your Jekyll configuration.

gems:
  - octopress-markdown-tag

Usage

Embed Markdown in HTML

Drop some markdown in your html, and it will render nicely


<!-- Some random HTML file-->
<div>
{% markdown %}

## That's right folks!

Markdown in your `HTML`!

- Any template
- Any time

{% endmarkdown %}
</div>

Convert included partials with markdown

Correctly render markdown files which are included in an HTML page.


<!-- Another random HTML file-->

<div>
{% markdown %}{% include coolcat.md %}{% endmarkdown %}
</div>

That’s pretty much it. Have fun!

Part 3 - Goodies

Chapter 3.1 - Social

Easy social integrations with Twitter, Facebook, Google+, Email and GitHub on any Jekyll site.

Installation

If you’re using bundler add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-social'
end

Then install the gem with Bundler

$ bundle

To install manually without bundler:

$ gem install octopress-social

Then add the gem to your Jekyll configuration.

gems:
  - octopress-social

Basics

All configuration for this plugin is optional. Some features, like follow buttons or comment tags require username. Other than that all configurations are only necessary if you want to modify the output of the tags.

Configurations are set in your site’s _config.yml. If for some reason these configurations conflict with another plugin, you can set them under the octopress_social key.

All tags respond to context. For example, in a post loop, {% tweet_button %} will automatically point to the current post. Used outside of a post loop, tags will refer to the current page.

Twitter

Configure this plugin in your site’s _config.yml. No configurations are required, just add your username if you want to use follow buttons or be mentioned in tweets. Here are the configuration defaults.

twitter:
  username:                               # Add your Twitter handle
  tweet_count:         false              # Show number of shares on Twitter
  size:                normal             # Or large
  embedded_link_color:                    # Set link color for embedded tweets

  follow_count:        false              # Show number of followers
  tweet_message:       ":title by :username :hashtags - :url" # With Tweet button Twitter add the URL last
  tweet_link_text:     Twitter            # Configure the link text
  tweet_link_title:    Share on Twitter   # Share link title
  profile_link_text:   Follow :username
  profile_link_title:  Follow :username on Twitter  # Profile link title text

To include hashtags, in your tweet message add them in the YAML front matter of your post or page, like this:

twitter_hashtag: tech  # A single hashtag
twitter_hashtags:      # Multiple hashtags
 - tech
 - kittens

If your site has multiple authors, you can configure the author’s twitter handle in a post’s YAML front-matter and the tweet button (or link) will mention them in the default message.

twitter_username: some_author

You can also configure a different default message in your post or page’s YAML front-matter:

tweet_message: "Yay Jekyll :title by :username - :url :hashtags"

Note: This plugin sets the twitter button’s “do not track” setting to ‘true’. I have no intention of making this configurable.

Twitter Tags

To use Twitter’s fancy buttons you’ll need to add this tag to your site’s layout before the closing body tag.


{% twitter_script_tag %} # Injects Twitter's widget.js.

Sharing tags:


{% tweet_button %}
{% tweet_link %}          # Tweet with a (no js) link

The tweet button and tweet link will open a new page with a composed tweet in the format in your Twitter configuration, :title by :username - :url :hashtags.

Follow tags:


{% twitter_follow_button %}
{% twitter_profile_link %}

Embed a tweet:


{% tweet status_url %}Tweet Text{% endtweet %}

This will generate a blockquote, much like this one:

<blockquote class="twitter-tweet" data-link-color="" lang="">
<p>[Tweet Text]</p>
<a href="[tweet_url]"> — @[user]</a>
</blockquote>

If you include the twitter widget.js in your site, this will automatically be replaced with one of Twitter’s fancy embedded tweets.

Facebook

Configure this plugin in your site’s _config.yml.

You don’t need to configure anything to start using this plugin but if you want to use the follow button or profile link, you’ll need to add your profile_id.

To get your profile_id, take a section from the url to your profile page https://www.facebook.com/[profile_id].

Here are the defaults:

facebook:
  app_id:                            # For a nicer (no js) sharing experience
  profile_id:                        # For follow button or profile link
  action:              like          # Or recommend
  share:               false         # Also add a share button
  layout:              button        # Choices: standard, box_count, button_count, button
  show_faces:          false
  colorscheme:         light         # Or dark
  kid_directed_site:   false         # Is your site directed at kids under 13?

  share_link_text:     Facebook            # Text for plain-old link
  share_link_title:    Share on Facebook   # Share link title text
  profile_link_text:   Friend on Facebook
  profile_link_title:  Friend on Facebook  # Profile link title text

  comment_count:       5             # Number of facebook comments to show by default
  comments_link_text:     Comments
  disabled_comments_text: Comments disabled  # Set to '' to output nothing when comments are disabled

These configurations are all based on Facebook’s widget configuration spec, visit that site for more info.

Facebook APP ID

If you want to use the fancy share link (lets you set default content for the share), you’ll need to get an app_id. For that you’ll have to register as a developer and go through the process to create an ‘app’. This is free and it doesn’t mean you’re developing software or anything, it’s just how Facebook wants to do this. Once you’ve created an app, go to the “Basic settings page” by clicking settings, and then finding the “Basic” link. There you should be able to find your App ID.

Facebook Tags

To use Facebook’s scripted features you’ll need to add this tag to your site’s layout before the closing body tag.


{% facebook_script_tag %} # Injects Facebook's widget.js.

Sharing tags:


{% facebook_like_button %}
{% facebook_send_button %}   # For private sharing
{% facebook_share_link %}    # share with a (no js) link

Friend and Follow tags:


{% facebook_follow_button %} # Requires a public profile
{% facebook_profile_link %}

Embed Facebook comments widget:


{% facebook_comments %}
{% facebook_comments_link %}   # Add a link that jumps right to your comments section.

Google+

Configure this plugin in your site’s _config.yml. The only required configuration is your user id. Here are the defaults.

gplus:
  id:                              # Your Google+ userid (for follow button or profile link)
  size:               medium       # choices: small, medium, standard, large
  width:                           # Specify width of button
  share_count:        false        # Show number of shares or +1s
  follow_count:       false        # Show numer of followers
  share_link_text:    Google+      # Text for plain-old link
  share_link_title:   Share on Google+   # Share link title
  profile_link_text:  Follow on Google+
  profile_link_title: Follow on Google+  # Profile link title

These configurations are based on Google’s web sharing widgets.

Google+ Tags

To use Google’s fancy buttons, you’ll need to add this tag to your site’s layout before the closing body tag.


{% gplus_script_tag %}   # Injects Google's widget.js.

Sharing tags:


{% gplus_one_button %}
{% gplus_share_button %}
{% gplus_share_link %}   # Share with a (no js) link

Follow tags:


{% gplus_follow_button %}
{% gplus_profile_link %}

Add convenient mail:to links which which helps readers contact you, or share your articles over email.

author:                # Your name

email:
  address:             # Your contact email
  share_subject:       :title by :author
  share_message:       :title by :author - :url
  share_link_text:     Email
  share_link_title:    Share via email
  contact_link_text:   Email :author
  contact_link_title:  Email :author

The share_subject and share_message configurations are used to generate a subject and body for a sharing email link.

Email Tags


{% email_share_link %}    # Share a post or page over email
{% email_contact_link %}  # Contac the site's author

If you want, you may customize an email subject or message on any page or post by setting the email_share_subject and email_share_message variables in the YAML front-matter.

GitHub

For now, this will just generate a GitHub profile link for you. Perhaps eventually I’ll do some cool stuff with the API and project listing. Configure this plugin in your site’s _config.yml.

github:
  username:                                  # Your GitHub username
  profile_link_text:  :username on GitHub
  profile_link_title: :username on GitHub    # profile link title text

Disqus Comments

Configure this plugin in your site’s _config.yml. The only required configuration is your Disqus shortname. Here are the defaults.

disqus:
  shortname:                                       # Your site's disqus identifier
  comments_link_text: Comments                     # Text label for comments link
  comments_disabled_link_text: Comments disabled   # Set to '' to not output a comments link when disabled

In any page or post, you can add these configurations to the YAML front-matter.

disqus_identifier:     # Unique identifier for this page's comments (defaults to full url)
disqus_title:          # Custom title for comments metadata (defaults to page/post title)
comments: false        # Disable comments for this page or post

Disqus Tags

These tags will help you integrate Disqus comments into your site.


{% disqus_comments %}       # Embed comments on a page
{% disqus_comments_link %}  # Add a link that jumps right to your comments section.

Disqus has a script that lets you add comment count to the link, but it’s so buggy, I’m not including it because I don’t want to deal with the support. You can still add it to your site manually.

Chapter 3.2 - Feeds

RSS feeds for Jekyll sites, featuring: - link-blogging - feeds for links and articles - Feeds for categories and tags - Multilingual support - automatic language specific feeds for all feed types

Installation

Using Bundler:

Add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-feeds'
end

Then install the gem with Bundler

$ bundle

Or install manually:

$ gem install octopress-feeds

Then add the gem to your Jekyll configuration.

gems:
  -octopress-feeds

Usage

For link blogging features (article-only and link-only feeds), install octopress-linkblog. For secondary language feeds, install octopress-multilingual.

Be sure your Jekyll configuration has a url, a name and an author.

url: http://yoursite.com/
name: Your Site Name
author: Guy McDude

Note: Relative URLs in your posts will be expanded based on your site’s url and basename configuration.

Next, add a <link> tag to your site’s <head>.


<head>
{% feeds %}
</head>

This would output:

<head>
<link href='http://yoursite.com/feed/' title='Your Site Name: Main Feed' rel='alternate' type='application/atom+xml'>
</head>

That’s it. When you build your site with jekyll build and this plugin will generate RSS feed(s) and generate the proper <link> tags.

Link-blogging

Install octopress-linkblog and posts with an external-url will be added to a feed at /feeds/links/index.xml while an articles-only feed will be generated at /feeds/articles/index.xml.

Multilingual support

If you are using octopress-multilingual, additional feeds will automatically be added for each language. Your feed urls will be organized by language. For example:

/en/feed/index.xml       # All English posts feed
/de/feed/index.xml       # All German posts feed

# Feeds added with octopress-linkblog
/en/feed/articles/index.xml    # English articles only feed
/en/feed/links/index.xml       # English link-posts only feed
/de/feed/articles/index.xml    # German articles only feed
/de/feed/links/index.xml       # German link-posts only feed

To change the URL for these pages, read the Feed Permalinks section below.

Configuration

To configure this plugin, first copy the plugin’s configuration file to _plugins/feeds/config.yml buy running:

$ octopress ink copy feeds --config-file

This will create a configuration file populated with the defaults for this plugin. Deleting this file will restore the default configuration.

Configuration defaults

feed_count: 20               # Maximum number of posts in a feed
posts_link_out: true         # Linkposts should direct visitors to the linked site
feed_excerpts: false         # Use post excerpts in feeds
category_feeds: false        # Add a feed for post categories
tag_feeds: false             # Add a feed for post tags
categories: []               # Only add feeds for these categories. (empty adds feeds for all categories)
tags: []                     # Only add feeds for these tags. (empty adds feeds for all tags)

read_more_label:  "Continue reading →"
permalink_label:  "Permalink"

titles:
  main_feed:      Posts - :site_name
  links_feed:     Links - :site_name
  articles_feed:  Articles - :site_name
  category_feed:  Posts in :category - :site_name
  tag_feed:       Posts tagged with :tag - :site_name

permalinks: 
  main_feed:      /feed/
  links_feed:     /feed/links/
  articles_feed:  /feed/articles/
  category_feed:  /feed/categories/:category/
  tag_feed:       /feed/tags/:tag/

Feed titles

The titles configuration allows you to control the title that RSS subscribers see for your feed.

As you’d expect, :site_name is replaced with the value from your site configuration and :category is replaced with the category for that feed.

If you want to change the title for other languages you can add a new language localized config file. For example if you have German feeds, you would add a config file at _plugins/feeds/config_de.yml and set titles for your German language feeds.

Feed permalinks

You can set the URL for the feed pages by configuring the permalinks setting.

If you are running a multilingual site with octopress-multilingual permalinks will be prepended with the lanugage code that corresponds with the posts in that feed. So /feed/ will become /en/feed/ and /de/feed/ and so on.

Excerpted feeds

Post excerpts are determined by Jekyll’s excerpt_separator configuration. It defaults to splitting your post at the first double line-break, \n\n. If you want more control over where the excerpt happens on your individual posts, You can change that to something like  and place that comment wherever you like in your post to split the content there.

Customizing feed templates

When you run $ octopress ink list feeds the includes and templates section might like this:

includes:
  - entry.xml
  - head.xml
 
templates:
 - articles.xml                  # template file
    /feed/articles/index.xml     # page generated from template
 - category.xml
 - links.xml
    /feed/links/index.xml
 - main.xml
    /feed/index.xml

To customize feed templates and inlcudes, Copy all of the plugin’s assets to _plugins/feeds/ by running this command:

octopress ink copy feeds --templates --includes

Any changes you make to these templates will override the templates in the plugin. If you want to revert to the defaults, simply delete any file you don’t care to override from the _plugins/feeds/ directory.

Chapter 3.3 - Linkblog

Adds link blogging features, along with some other niceties to any Jekyll site.

Installation

Using Bundler

Add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-linkblog'
end

Then install the gem with Bundler

$ bundle

Manual Installation

$ gem install octopress-linkblog

Then add the gem to your Jekyll configuration.

gems:
  - octopress-linkblog

Usage

Post features

With the gem installed, your site’s posts will automatically have new data attributes.

post.title - The post title, properly capitalized with titlecase.
post.title_html - The post title, unorphaned and with html wrapping any post markers.
post.title_text - The post title with markers, but all in plain text (great for RSS).
post.title_url - The URL that post titles should link to.
post.title_link - A <a> tag filled with the title_html pointing to the title_url.
post.permalink - A <a> tag containing your configuration’s pearmalink_label pointing to the post’s URL.
post.linkpost - A boolean indicating whether the post is a link post.

Here is an example. Given the following YAML front-matter:

---
title: cats are awesome
external_url: http://cats.example.com
---

The post would have these attributes:

title        => Cats Are Awesome
title_html   => Cats Are&nbsp;Awesome&nbsp;<span class='post-marker post-marker-after'>→</span>
title_text   => Cats Are Awesome →
title_url    => http://cats.example.com
title_link   => <a href='http://cats.example.com' class='article-link linkpost'>...</a>
permalink    => <a href='http://your-site.com/posts/1' class='permalink'>Permalink</a>
linkpost     => true

Note: the <a> in this demo has been shortened, but it will contain the title_html.

Site features

In addition, the site payload will have two new post arrays:

site.articles - Will contain standard posts only.
site.linkposts - Will contain only posts with an external_url

This may have many uses, but one in particular is the option to allow RSS feeds for each type of post.

Configuration

You can configure this plugin in your site’s _config.yml under the linkblog key. Here are the defaults.

linkblog:
  linkpost:
    marker: →
    marker_position: after
  posts:
    marker: false
    marker_position: before

  titlecase: true
  unorphan: true
  permalink_label: Permalink

Part 4 - Themes

Chapter 4.1 - Genesis

A new theme build on Octopress Ink.

Note: This theme is in alpha development. What’s left to do? See the issues.

Installation

If you’re using bundler add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-genesis-theme'
end

Then install the gem with Bundler

$ bundle

To install manually without bundler:

$ gem install octopress-genesis-theme

Then add the gem to your Jekyll configuration.

gems:
  - octopress-genesis-theme

Usage

This is best demonstrated on a new Jekyll site:

Create a new Jekyll site.
Add some posts or pages.
Ensure that posts have the layout theme:post, and pages theme:page
Run jekyll serve and check it out.

Configuration

To configure this theme, create a _plugins/theme/config.yml and add your settings. Here are the defaults.

# Settings for main header
title: My Octopress Blog
subtitle:
 
# Links for main navigation
main_nav:
  - { url: '/', title: 'Posts' }
  - { url: '/archive/', title: 'Archive' }
  - { url: '/feed/', title: 'Subscribe' }

# Link labels
permalink_label: "Permalink"
read_more_label: "Continue Reading →"

# Show excerpts on post index
excerpt_posts: true
# Excerpt linkposts on index
excerpt_linkposts: false

search: google

sharing:
  - facebook
  - twitter
  - gplus
  - email

# Defaults to sharing with links (for speed and privacy)
# To use javascript share buttons, set share_with: buttons
share_with: links

# Embed comments, options: false, facebook, disqus
comments: false

# Center the text in post and page headings.
center_headings: true

You can also easily overwrite stylesheets, layouts, partials and basically everything about this plugin by adding a copy of that file in the _plugins/theme directory. More on that later.

Multilingual Support

If you’re going to be building a multilingual site, be sure to install octopress-multilingual and this theme will automatically generate language specific pages for your:

Posts index
Archive page
Category indexes (if you use them)
Tag indexes (if you use them)

Also you will be able to set theme configurations for each language. For example to configure theme settings for your German pages, you’d create a _plugins/theme/config_[lang].yml and add whatever settings you want to override.

Part 5 - Miscellaneous

Chapter 5.1 - Multilingual

Add multiple language features to your Jekyll site. This plugin makes it easy to:

Add language-specific post indexes, archives, and RSS feeds.
Link between translated posts and pages.
Use language in your permalinks.
Cross-post a single post to all languages.
Add translation dictionaries to simplify site templates.
Tag and category indexes are automatically filtered by language.

Installation

If you’re using bundler add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-multilingual'
end

Then install the gem with Bundler

$ bundle

To install manually without bundler:

$ gem install octopress-multilingual

Then add the gem to your Jekyll configuration.

gems:
  - octopress-multilingual

An important note

There is no Jekyll standard for multilingual sites and many plugins will not work properly with this setup. Octopress and it’s plugins are being designed to support multilingual features, but without a standard, some use-cases may be overlooked. If you have a problem with an Octopress plugin supporting your multilingual site, please file an issue and we’ll do our best to address it.

Note: First-party Octopress plugins are designed to support multilingual sites but other plugins may not work how you’d expect on multilingual sites. Modifying plugins is beyond the scope of this guide.

Also, if you are using flags to represent languages on your site, you might like to read, Why flags do not represent language.

Helpful Plugins

These plugins automatically add multilingual features to your site when used with Octopress Multilingual.

Octopress Linkblog adds link-blogging indexes (articles-only, links-only) and feeds for each language.
Octopress Feeds adds RSS feeds for each language.

Setup

When adding this plugin to your site, you will need to:

Configure your site’s main language, e.g. lang: en.
Add a language to the YAML front-matter of your posts, e.g. lang: de.
Add post indexes and RSS feeds for secondary languages.

First, be sure to configure your Jekyll site’s main language. An site written primarily in English would add this to its Jekyll configuration:

lang: en

Here we are setting the default language to English. Posts without a defined language will be treated as English posts. For a list of standard language codes, refer to ISO 639-1. You can also use the [language]-[region] method of setting your site’s language, like en-us for American English or de-at for Austrian German.

Setting a language for pages or posts

Specify a page or post’s language in the YAML front matter.

title: "Ein nachdenklicher Beitrag"
lang: de

You can, refer to a page or post language by page.lang or post.lang. This plugin adds the filter language_name which can convert the language short-name into the native language name. For example:


{{ en | language_name }} # English
{{ de | language_name }} # Deutsch
{{ es | language_name }} # Español

Many common language codes are supported, but you can add to or override these in Jekyll’s site configuration:

language_names:
  es: Spanish
  omg: WTFBBQ

Indexes, RSS feeds and Archives.

If you are writing English and German posts, you’ll want an English-only and a German-only post index. To do that, just set the language in the YAML front-matter of your post-index.

For example, this will loop through only German posts:


---
lang: de
---
{% for post in site.posts %} ... {% endfor %}

And this will loop through only English posts:


---
lang: en
---
{% for post in site.posts %} ... {% endfor %}

If your default post index is at /index.html you should create additional indexes for each secondary language. If you also write in German, you can create a posts index at /de/index.html. This approach will work for post archives and RSS feeds, though if you are using octopress-feeds, RSS feeds for each language will be generated automatically.

How does it work? First this plugin groups all of your posts by language. Then at build time, any page with a language defined will have its posts filtered to display only matching languages. This also works for site.categories and site.tags. If your site uses octopress-linkblog to publish link-posts, your site.articles and site.linkposts will be filtered as well.

Site template language dictionaries

It’s annoying to have to write multiple site layouts and includes when the only differences are translated words. Octopress Multilingual adds language dictionaries to make this much easier. In your site’s _data directory you can add language dictionaries with the file naming pattern lang_[language_code].yml. For example:

_data
  lang_en.yml
  lang_de.yml

Your files might look like this:

# lang_en.yml
title: English title

# lang_de.yml
title: Deutsch titel

Now in your layouts or includes you can reference these dictionaries under the global variable lang. The configured page or post language will determine which language dictionary is used. For example:


# On a page or post where lang: en
{{ lang.title }} => English title

# On a page or post where lang: de
{{ lang.title }} => Deutsch titel

If no language is configured for a page or post, it will default to the site’s default language.


# No page lang, site is configured lang: en
{{ lang.title }} =>  English title

Since these are Jekyll data sources, these dictionaries can also be accessed at site.data.lang_en and site.data.lang_de. This plugin merely adds the global lang variable and swaps out context based on configured language.

Link between translated posts or pages

URLs can change and manually linking to translated posts or pages isn’t the best idea. This plugin helps you link posts together using a shared translation ID. With octopress, you’ll be able to automatically add translation IDs to pages and posts. Then you can reference the array of translations with post.tranlsations or page.translations. Here’s the syntax:

$ octopress id path [path path...]

This will create a unique key and automatically write it to the YAML front-matter each of the pages or posts you pass in. Here’s an example:

$ octopress id _posts/2015-02-02-english-post.md _posts/2015-02-02-deutsch-post.md _posts/2015-02-02-espanol-post.md

This will add translation_id: fcdbc7e82b45346d67cced3523a2f236 to the YAML front-matter of each of these posts. There’s nothing special about this key except that it is unique. If you want to write your own you can, it’ll work just fine.

When you have posts or pages with a translation_id you can use the translations or translation_list tags to list links to translated posts or pages. For example:


{% translations page %} # On a page/post layout
{% translations post %} # In a post loop

# Which outputs:
<a class='translation-link lang-de' href='/de/2015/02/02/deutsch-post'>Deutsch</a>, <a class='translation-link lang-es' href='/es/2015/02/02/espanol-post'>Español</a>

# If you prefer a list:
{% translation_list post %}

# Which ouputs:
<ul class='translation-list'>
  <li class='translation-item lang-de'>
    <a class='translation-link lang-de' href='/de/2015/02/02/deutsch-post'>Deutsch</a>
  </li>
  <li class='translation-item lang-es'>
    <a class='translation-link lang-es' href='/es/2015/02/02/espanol-post'>Español</a>
  </li>
</ul>

If you’d rather access translated posts manually, you can loop through the translations like this:


{% if page.translated %}
  Translations: {% for t in page.translations %}
    <a href="{{ t.url }}">{{ t.lang | language_name }}</a>
  {% endfor %}
{% endif %}

Reference posts by language

All posts are grouped by language and can be accessed directly with site.posts_by_language. For example:


{% for post in site.posts_by_language.de %}  # German posts
{% for post in site.posts_by_language.en %}  # English posts

If you have octopress-linkblog installed, you can access groups of link-posts and articles too.


{% for post in site.linkposts_by_language.de %}  # German linkposts
{% for post in site.articles_by_language.de %}   # German articles

Cross-posting languages

If you would like to write a post which shows up in indexes and feeds for every language, set lang_crosspost: true in your post’s YAML front-matter.

title: "Ein nachdenklicher Beitrag"
lang: de
lang_crosspost: true

This post will show up with every language. However, it will be treated exactly like a post written in German and will have one canonical URL.

Language in permalinks

This plugin does not use categories to add language to URLs. Instead it adds the :lang key to Jekyll’s permalink template. Any post with a defined language will have its language in the URL. If this changes URLs for your site, you probably should set up redirects.

If you define your own permalink style, you may use the :lang key like this:

permalink: /posts/:lang/:title/

If you have not specified a permalink style, or if you are using one of Jekyll’s default templates, your post URLs will change to include their language. When using Jekyll’s pretty url template, URLs will look like this:

/site_updates/en/2015/01/17/moving-to-a-multilingual-site/index.html
/site_updates/de/2015/01/17/umzug-in-eine-mehrsprachige-website/index.html

This plugin updates each of Jekyll’s default permalink templates to include :lang.

pretty  => /:lang/:categories/:year/:month/:day/:title/
none    => /:lang/:categories/:title.html
date    => /:lang/:categories/:year/:month/:day/:title.html
ordinal => /:lang/:categories/:year/:y_day/:title.html

If you don’t want language to appear in your URLs, you must configure your own permalinks without :lang.

Temporary language scoping

Using the set_lang liquid block, you can temporarily switch languages while rendering a portion of your site. For example:


{{ page.lang }}    # => 'en'
{{ site.posts }}   # => All posts

{% set_lang de %}
  {{ page.lang }}  # => 'de'
  {{ site.posts }} # => German posts
{% endset_lang %}

{{ page.lang }}    # => 'en'
{{ site.posts }}   # => All posts

The set_lang tag will also accept variables, for example:


{% assign lang = 'de' %}
{% set_lang lang %}   # equivilent to {% set_lang de %}

# On some page
{% include some_partial.html lang='de' %}

# In _includes/some_partial.html
{% set_lang include.lang %}    # equivilent to {% set_lang de %}

If you have the octopress-linkblog plugin installed, this will also change languages for your site.articles and site.linkposts loops.

Chapter 5.2 - Date Format

Put nicely formatted dates on any post or page.

Installation

Add this line to your application’s Gemfile:

gem 'octopress-date-format'

And then execute:

$ bundle

Or install it yourself as:

$ gem install octopress-date-format

Next add it to your gems list in Jekyll’s _config.yml

gems:
  - octopress-date-format

Usage

Any post (or page with a date) will automatically have some new date attributes.

date - The date, 2014-07-03 14:08:00 +0000
date_text - The formatted date, Jul 3rd, 2014
time_text - The formatted time, 2:08 pm
date_xml - The XML schema formatted date, 2014-07-03T14:08:00+00:00
date_html - The formatted date in a <time> tag.
date_time_html - The formatted date and time in a <time> tag.

Here’s an example of what would be rendered with ``.

<time class='entry-date' datetime='2014-07-03T14:08:00+00:00'>
  <span class='date'>
    <span class='date-month'>Jul</span>
    <span class='date-day'>3</span><span class='date-suffix'>rd</span>,
    <span class='date-year'>2014</span>
  </span>
  <span class='time'>2:08 pm</span>
</time>

If you update a post or page and want to display this in a template, add this to YAML front-matter, date_updated: 2014-07-03 15:03:15 and your post will have updated date attributes as well.

updated - The date, 2014-07-03 15:03:15 +0000
date_updated_text - The formatted date, Jul 3rd, 2014
time_updated_text - The formatted time, 3:03 pm
date_updated_xml - The XML schema formatted date, 2014-07-03T15:03:15+00:00
date_updated_html - The formatted date in a <time> tag.
date_time_updated_html - The formatted date and time in a <time> tag.

Of course you can use Liquid conditionals when outputting an updated date.


{% if post.updated %}Updated: {{ post.date_time_updated_html }}{% endif %}

Configuration

You may change the formatting of the dates and times in Jekyll’s configuration file. Here are the defaults:

date_format: 'ordinal'     # July 3rd, 2014
time_format: '%-I:%M %P'   # 2:08 pm

To choose a different format, use a Ruby strftime compatible string. For example:

date_format: "%Y-%m-%d"  # e.g. 2014-07-03
time_format: "%H:%M"     # 24 hour time

Chapter 5.3 - Filters

A set of handy liquid filters used by Octopress.

full_urls - Replace relative URLs with absolute URLs (searches for href and src properties).
full_url - Replace a relative URL with an absolute URL.
canonical_url - Convert a URL to the proper canonical version.
titlecase - Properly capitalize titles with John Gruber’s Title Case.
smartquotes - Smartly curl your quotation marks with John Gruber’s Smarty Pants.
unorphan - Insert a non-breaking space between the last two words in a title.
sluggify - Replaces all non-word characters in a string with dashes.
classify - An alias for sluggify (seems appropriate when working with CSS class names).
compact_newlines - Compact groups of empty lines into one, because Liquid templates have lots of whitespace.
join_lines - Remove all new lines, joining each line with a separator. (defaults to a space).
strip_url_protocol - Remove the protocol before a URL, e.g. http:// or https://.

Also, not a filter, but this adds excerpted (true/false) to post’s data. Meaning you can use {% if post.excerpted %} in a post loop.

Installation

If you’re using bundler add this gem to your site’s Gemfile in the :jekyll_plugins group:

group :jekyll_plugins do
  gem 'octopress-filters'
end

Then install the gem with Bundler

$ bundle

To install manually without bundler:

$ gem install octopress-filters

Then add the gem to your Jekyll configuration.

gems:
  -octopress-filters

Examples

Full URLs

Any relative links in your site will be expanded with the url configuration in Jekyll’s _config.yml. This filter only affects URLs beginning with / inside of href or src attributes.


{{ post.content | full_urls }}

You might use this if you’re working on an RSS feed, you’ll need to be sure all relative URLs in your content are expanded to full URLs.

Full URL

This filter prepends input with the url configuration in Jekyll’s _config.yml.


{{ post.url | full_url }}

Canonical URL

This filter expands the URL to be a full URL, then removes “index.html” if it is present. Here are some examples.


{{ "about/index.html" | canonical_url }}  //=> http://example.com/about/
{{ "about.html" | canonical_url }}        //=> http://example.com/about.html
{{ "/" | canonical_url }}                 //=> http://example.com/

Titlecase


{{ post.title | titlecase }}  //=> This Is a Properly Capitalized Title

Smartquote


{{ post.content | smartquotes }}

Unorphan


{{ post.title | unorphan }}  //=> This Is a Properly Capitalized&nbsp;Title

Sluggify/Classify

<article class="">

Compact newlines


{{ content | compact_newlines }}

Join lines


{% capture page_title %}
{{ page.title }}
{{ site.header.title }}
{% endcapture %}

<head>
  <title>{{ page_title | join_lines: " - " }}</title>
  …

Strip URL protocol


{{ site.url }}                        # https://some-site.com/
{{ site.url | strip_url_protocol }}   # some-site.com/

Excerpted posts

In your templates, you may want to show different content if a post is excerpted. This plugin automatically searches each post for the excerpt separator and adds the excerpted state to the post data. So you can do something like this.


{% if post.excerpted %}
  {{ post.excerpt }}
  <a href="{{ post.url }}"Continue reading →</a>
{% else %}
  {{ post.content }}
{% endif %}

Jekyll has an excerpt_separator configuration which lets you define how Jekyll selects your post excerpts. By default this config is set to "\n\n", but redefining the config to something like excerpt_separator:  makes it easy to decide which content is excerpted, or even whether posts have excerpts at all.