Jekyll Plugins

The 18F site has a mix of plugins we wrote, and plugins written by the Jekyll community. This page describes what they're for and explains how to use them.

We wrote

All the plugins we wrote are ruby files in the _plugins directory in the 18f.gsa.gov repo.

author

The author file contains several Liquid filters and a two template tags. The liquid filters manipulate a string within a layout, include, or even a Jekyll document. You use them with a pipe after the string, and the filter after the pipe. For example: {{ "STRING" | downcase }} will print "string" in the template. Template tags trigger a command to output something to the page. They usually look like this: {% command %}`

Filters

• lookup: Looks the string up in a specified data file and returns a specific key. For example: {{ "boone" | lookup:"authors,full_name" }} will look for boone in authors and return full_name.
• team_link: Looks for either a team member or author matching the string and returns their full_name wrapped in a link to their team page or other URL. For example: {{ "boone" | team_link }} will look for a teammate named "boone" and, if found, will return a link to their profile page. If a teammate can't be found, the plugin looks for an author and uses the url if listed. For example: {{ "deniseturnerroth" | team_link }}` will find the matching author and link to her listed url.
• with_pic: Looks for an image in /assets/images/team matching the specified string and prints an img tag. For example, {{ "boone" | with_pic }} returns: "<img class='img-circle team-img bio-clip' src='/assets/images/team/boone.jpg' alt='18F team member Greg Boone'>"

Template tags

• authored_posts: Finds all posts authored by the individual whose name is assigned to the page. It is designed for use with the team pages. See the source for Aaron Snow's for an example of how the frontmatter should be structured. You must also pass a value to the variable heading with a pipe. Example: {% authored_posts | heading=h3 %} will list the posts for the current author under an h3 heading. See it in use on the sidebar include.
• author: Returns an author's full_name wrapped in a span tag. This is not currently in use in any templates or includes.

Embeds

A single filter embed that takes a YouTube url like https://youtube-nocookie.com/blahblahblah and spits out the embed HTML at the correct dimensions. See it in action on this blog post. We should consider replacing this with a plugin that fully implements oembed.

Generate Data API

A single generator that outputs the files in _data to an /api/ endpoint. Not perfect and if we implement search with the pages_api_search plugin we should deprecate this. It likely does not get much use as it is currently written.

Related posts

A template tag that links the current post to others with similar tags or authors. Use it with `{% related_posts %} and optionally pass parameters to format the list. By default it will print five posts in an unordered list. See it working in the post layout.

Examples:

{% related_posts %} in a layout will print

<ul>
  <li><a href='#{@baseurl}#{post.url}'
class='related_posts'>"Title of the related post"</a></li>
</ul>

The <li> block will print once for each post returned.

• {% related_posts | ol li %} in a layout will print

<ol>
  <li><a href='#{@baseurl}#{post.url}'
class='related_posts'>"Title of the related post"</a></li>
</ol>

Like above, the <li> block will repeat for each post.

• {% related_posts | span p %} will print:

<span>
  <p><a href='#{@baseurl}#{post.url}'
class='related_posts'>"Title of the related post"</a></p>
</span>

The <p> block will repeat for each post

Team

A single filter, team_photo for returning a teammate's photo given a string with their photo's filename. For example {{ "boone" | team_photo }} will look for a file at /assets/images/team/boone.jpg. See it working on the headline include, the /team/ page and in several posts where team members names and photos are used.

Dashboard

A generator that creates pages from a data file at _data/projects.yml. Data from each project listed there is added to the page object at generation time and available to the dashboard layout.

Jekyll Community

• 'jekyll-sitemap: Generates a sitemap for Google Webmaster Tools
• gem 'jekyll-archives': Auto-generates archives for posts by date, tag, and category
• 'jekyll-paginate': Creates an archive page for each set of x posts.
• 'jekyll-redirect-from': Allows us to create redirects when renaming a post published with the incorrect name or date, or when changing the name of a popular page or tag.
• 'jekyll_frontmatter_tests': Allows us to define tests for each document type. (Technically we wrote this but it's a gem.)
• 'jekyll-feed': Creates a standard RSS feed for the blog.
• 'jekyll-seo-tag': Add metadata tags for search engines and social networks to better index and display your site's content.