guides_style_18f: 18F Guides style gem
Gemfile, include the following:
group :jekyll_plugins do gem 'guides_style_18f' end
assets/css/styles.scss file that contains at least the following:
--- --- @import "guides_style_18f";
theme: guides_style_18f defaults: - scope: path: "" values: layout: default
Build the site per usual, and observe the results.
Here are some other features that can be enabled via
# 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
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
Add a new page will
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
There are two options for search.
- Generates a search index locally, which has the advantage of being self-contained. This means you can easily test search locally, on a staging site, etc.
- Search results are shown in your site's layout
- Slows down your build
Usage: see the instructions.
- A hosted service, so your site has fewer moving parts.
- A more full-featured search engine
- Search results show a preview of the text on the page, with highlighted term(s)
- Provides analytics
- You need to register your site
- Can't test search results locally
Register your site at search.gov.
Add the following to your
search_gov_handle: <your Site Handle from the search.gov Settings page>
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@example.com:18F/guides-template.git $ git clone firstname.lastname@example.org:18F/guides-style.git
Gemfile of the Jekyll site's repository, include the following:
group :jekyll_plugins do gem 'guides_style_18f', :path => '../guides-style' end
then build the site with
bundle exec jekyll serve. You can find the different style assets and templates within subdirectories of
lib/guides_style_18f directories of this repository. Edit
those, then rebuild the Jekyll site as usual to see the results.
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.