guides_style_18f
: 18F Guides style gem
Provides consistent style elements for Jekyll-based web sites based on the 18F Guides Template. The 18F Guides theme is based on DOCter from CFPB.
Usage
In your Gemfile
, include the following:
group :jekyll_plugins do
gem 'guides_style_18f'
end
Add an assets/css/styles.scss
file that contains at least the following:
---
---
@import "guides_style_18f";
Then in your _config.yml
file,
add the following (you may need to remove any layout:
front matter from existing pages for
this to take effect):
defaults:
-
scope:
path: ""
values:
layout: "guides_style_18f_default"
Build the site per usual, and observe the results.
Additional features
Here are some other features that can be enabled via _config.yml
:
# To use the shared 18F Guides Teamplate assets when deploying to
# pages.18f.gov, to avoid having to rebuild the site for minor style and
# script updates:
asset_root: /guides-template
# This adds the "back to" breadcrumb link under the page title:
back_link:
url: "https://pages.18f.gov/guides/"
text: Read more 18F Guides
# If you use Analytics, add your code here:
google_analytics_ua: UA-????????-??
# If you want all of the navigation bar entries expanded by default, add this
# property and it to true:
expand_nav: true
Additional scripts and styles
If you'd like to add additional scripts or styles to every page on the site,
you can add styles:
and scripts:
lists to _config.yml
. To add them to a
particular page, add these lists to the page's front matter.
Alternate navigation bar titles
If you want a page to have a different title in the navigation bar than that
of the page itself, add a navtitle:
property to the page's front matter:
---
title: Since brevity is the soul of wit, I'll be brief.
navtitle: Polonius's advice
---
Selectively expanding navigation bar items
If you wish to expand or contract specific navigation bar items, add the
expand_nav:
property to those items in the navigation:
list in
_config.yml
. For example, the Update the config file
entry will expand
since the default expand_nav
property is true
, but Add a new page
will
remain collapsed:
expand_nav: true
navigation:
- text: Introduction
internal: true
- text: Add a new page
url: add-a-new-page/
internal: true
expand_nav: false
children:
- text: Make a child page
url: make-a-child-page/
internal: true
- text: Update the config file
url: update-the-config-file/
internal: true
children:
- text: Understanding the `baseurl:` property
url: understanding-baseurl/
internal: true
Development
First, choose a Jekyll site you'd like to use to view the impact of your updates and clone its repository; then clone this repository into the same parent directory. For example, to use the 18F Guides Template:
$ git clone [email protected]:18F/guides-template.git
$ git clone [email protected]:18F/guides-style.git
In the Gemfile
of the Jekyll site's repository, include the following:
group :jekyll_plugins do
gem 'guides_style_18f', :path => '../guides-style'
end
You can find the different style assets and templates within subdirectories of
the assets
and lib/guides_style_18f
directories of this repository. Edit
those, then rebuild the Jekyll site as usual to see the results.
Public domain
This project is in the worldwide public domain. As stated in CONTRIBUTING:
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.