18F UI style guide

For developers

18f.gsa.gov, and many 18F websites deployed to Federalist use Jekyll to build static, maintainable websites.

One of the core features of Jekyll is the Liquid templating language, which has a series of filters and tags that allow developers programmatically generate content.

Jekyll and Liquid do quite a bit, but sometimes they aren’t enough for a project’s specific needs. When the built-in functionality that Jekyll provides isn’t enough, it is possible to build or borrow plugins to extend Jekyll.


Plugin gems

18f.gsa.gov is using several Ruby gems plugins:

Plugin gem Description
jekyll-archives creates and manages blog-related pages.
jekyll-feed generates an Atom (RSS-like) feed at /feed.xml.
jekyll-paginate allows for pagination of blog pages, or pages with long lists of items.
jekyll-redirect-from enables redirecting from pages that are no longer active.
jekyll-seo-tag adds metadata tags for search engines and social networks.
jekyll-sitemap generates a sitemap at /sitemap.xml. This makes it easier for search engines to find us.
jekyll_frontmatter_tests tests to see if the correct front matter (meta data) is present on pages throughout our website.
jekyll_pages_api generates a JSON file at /api/v1/pages.json that serves as the base for a site search engine.
jekyll_pages_api_search search engine that uses jekyll_pages_api
jekyll_oembed creates a Liquid tag that uses OEmbed

Custom plugins

18f.gsa.gov uses many custom plugins for more specific site needs:

Custom plugin name Description
author.rb creates two filters, lookup and team_link.
author_data.rb Creates an API for using data pertaining to authors throughout the site.
update_author_data.rb Uses the AuthorData API to update the list of published authors. This will happen automatically every time the site builds.
embed.rb legacy filter for embedding content within the site. The current approach is to use an OEmbed plugin.
liquify.rb liquid parser.
markdown.rb markdown parser.
matching_posts.rb creates a match_posts filter that creates a list of posts belonging to a specific author.
team.rb creates a team_photo filter that matches an author to their provided team photo. More documentation.
utility.rb A list of Liquid filters that can be used for a variety of purposes: clip_char, hash_link, matches_url, debug, find_collection, where_obj, in_groups, and weighted_sort.