uswds-jekyll 3.0.0 → 5.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f8833f4d71fde3ce27a1a1e93a4668d850fabd94
-  data.tar.gz: 076066966ac5df1f30f5a700947d5934c4fda813
+SHA256:
+  metadata.gz: 552f833b8c33993f2f5b0c670b2e29e375b3ab4f9484154ca4487bfb3c907160
+  data.tar.gz: 357f8e3b7448a757997279b3bae773b372d2413977f0f4cfbd4e19f27bd7d9c0
 SHA512:
-  metadata.gz: 587a658fb06380eb70d10527ef86ad9a6a70883e21dbc00af0285dac43bf1d75ef9c7b0f725525a685c4a2cb90a3bb624835cb3e9b7e6934a7da654e3b554dd8
-  data.tar.gz: b4694ce851e925d33a86260fa3b0dac4684e5c1cc2ac739f5f1dec7255d123049f03e9e99429122e535897cade21643bb697b61b3931e71803daa9374516e278
+  metadata.gz: a88852b3c1997c9660e55dc3dfb1b436facc3526ea4adca8a58fc06d20bd6b11a36847d3c39a798cc625286a8ec7a3a784f4021f68e02e2053a60a3e29a2e7bd
+  data.tar.gz: e4d77d84905057cd33a187f8f5a05eee25c1f1112ee3cc4941b8aff33b01980a600a83e9a6e9ae7b69045ccc0ebe51acbf154380c7db77f0b05d5939252f0be1

data/README.md

@@ -4,164 +4,146 @@ This is a [Jekyll theme](https://jekyllrb.com/docs/themes/) for the
 [U.S. Web Design System](https://designsystem.digital.gov).
 
 ## Table of contents
+
 1. [Installation](#installation)
-    - [Development](#development)
-    - [Versioning](#versioning)
+   - [Versioning](#versioning)
 1. [Configuration](#configuration)
-    - [Site title](#site-title)
-    - [Navigation](#navigation)
-    - [Page subnavigation](#page-subnavigation)
-    - [Search](#search)
-    - [Analytics](#analytics)
-    - [Last modified date](#last-modified-date)
+   - [Site title](#site-title)
+   - [Site description](#site-description)
+   - [Navigation](#navigation)
+   - [Page subnavigation](#page-subnavigation)
+   - [Hero](#hero)
+   - [Tagline intro](#tagline-intro)
+   - [Graphics list](#graphics-list)
+   - [Color and font configuration](#color-and-font-configuration)
+   - [Search](#search)
+   - [Analytics](#analytics)
+   - [Last modified date](#last-modified-date)
+   - [Anchor JS](#anchor-js)
 1. [Assets](#assets)
-    - [Stylesheets](#stylesheets)
-    - [Scripts](#scripts)
-    - [Asset load order](#asset-load-order)
+   - [Stylesheets](#stylesheets)
+   - [Scripts](#scripts)
+   - [Asset load order](#asset-load-order)
 1. [Customization](#customization)
-    - [Customizing with Sass](#customizing-with-sass)
-    - [Customizing with CSS overrides](#customizing-with-css-overrides)
-    - [Overriding includes and layouts](#overriding-includes-and-layouts)
+   - [Customizing with Sass](#customizing-with-sass)
+   - [Customizing with CSS overrides](#customizing-with-css-overrides)
+   - [Overriding includes and layouts](#overriding-includes-and-layouts)
 1. [Components](#components)
-    - [Header](#header)
-    - [Footer](#footer)
+   - [Header](#header)
+   - [Footer](#footer)
 1. [Layouts](#layouts)
-    - [Default](#layout-default)
-    - [Page](#layout-page)
-    - [Home](#layout-home)
-    - [Post](#layout-post)
-    - [Search results](#search-results)
-
-
+   - [Default](#layout-default)
+   - [Page](#layout-page)
+   - [Home](#layout-home)
+   - [Post](#layout-post)
+   - [Project](#layout-project)
+   - [Team member](#layout-team-member)
+1. [Migration guide](#migration)
+1. [Development](#development)
 
 ## Installation
 
 1. Install the theme as a Ruby Gem by adding it to your `Gemfile`
    like so:
 
-    ```ruby
-    gem 'uswds-jekyll'
-    ```
+   ```ruby
+   gem 'uswds-jekyll'
+   ```
 
 1. Fetch and update your bundled gems by running:
 
-    ```sh
-    bundle
-    ```
+   ```sh
+   bundle
+   ```
 
 1. Set the `theme` in your site's Jekyll configuration,
    `_config.yml`:
 
-    ```yml
-    theme: uswds-jekyll
-    ```
+   ```yml
+   theme: uswds-jekyll
+   ```
 
 You will need to restart your Jekyll server to see the effects.
 
 ### Install as a new Jekyll site
 
 1. Create a new Jekyll site:
-    ```
-    jekyll new
-    ```
+   ```
+   jekyll new
+   ```
 1. Replace the default `gem "minima", "~> 2.0"` gem with the `uswds-jekyll` gem in your `Gemfile`:
 
-    ```ruby
-    gem 'uswds-jekyll', :git => 'https://github.com/18F/uswds-jekyll.git'
-    ```
+   ```ruby
+   gem 'uswds-jekyll'
+   ```
 
 1. Set the `theme` in your site's Jekyll configuration,
    `_config.yml`:
 
-    ```yml
-    theme: uswds-jekyll
-    ```
-1. Fetch and update your bundled gems by running:
+   ```yml
+   theme: uswds-jekyll
+   ```
 
-    ```sh
-    bundle
-    ```
-1. Run Jekyll `jekyll serve` to build your site locally at http://localhost:4000/
+1. Fetch and update your bundled gems by running:
 
-### Development
+   ```sh
+   bundle
+   ```
 
-To develop this theme and/or test it locally:
-
-1. Clone this repo
-1. Run Jekyll (`jekyll serve`) in the local clone of this repo;
-   **or**
-1. Create a new Jekyll project, follow the
-   [installation](#installation) instructions, then change your
-   `Gemfile` to point at the local clone of this repo:
-
-    ```ruby
-    gem 'uswds-jekyll', :path => '../path/to/uswds-jekyll'
-    ```
-### Publish to Rubygems
-1. Update `spec.version = "NUMBER HERE"` in the uswds-jekyll.gemspec file to the version you want to publish
-1. Run `bundle install`
-1. Add a PR for the update and get it merged
-1. Run `bundle exec rake release`
-1. Add a GitHub release to the releases page with the same version number
-1. You should see the latest version here https://rubygems.org/gems/uswds-jekyll
+1. Run `bundle exec jekyll serve` to build your site locally at http://localhost:4000/
 
 ### Versioning
 
-To reference a specific version of this plugin:
+To reference a specific version of this theme:
 
 1. Visit the [releases page](https://github.com/18F/uswds-jekyll/releases) and
    decide which version you want to use.
 1. Specify the version in your `Gemfile`.
 
-    ```ruby
-    gem 'uswds-jekyll', '1.4.1'
-    ```
+   ```ruby
+   gem 'uswds-jekyll', '~> 5.0'
+   ```
 
 ## Configuration
 
 Configuration of common elements ([header](#header),
-[footer](#footer), [navigation](#navigation), etc.) happens in your
-project's [data files](https://jekyllrb.com/docs/datafiles/). See
-this project's [data directory](_data) for reference configurations
+[footer](#footer), [navigation](#navigation), etc.) happens in your project's [data files](https://jekyllrb.com/docs/datafiles/). See this project's [data directory](_data) for reference configurations
 of each component.
 
-The [default layout](#layout-default) also provides a mechanism for
-automatically including [stylesheets](#stylesheets) and
-[scripts](#scripts) on a site-wide, layout-wide, and per-page
-basis. See [asset load order](#asset-load-order) for more
-information.
-
+The [default layout](#layout-default) also provides a mechanism for automatically including [stylesheets](#stylesheets) and [scripts](#scripts) on a site-wide, layout-wide, and per-page basis. See [asset load order](#asset-load-order) for more information.
 
 ### Site title
 
-You can change your site's title with the `title` field in your
-`_config.yml`.  If you want to provide an alternate title for use
-_only_ in the site header, you can set the `title` field in
-`_data/header.yml`.
+You can change your site's title with the `title` field in `_config.yml`. If you want to provide an alternate title for use _only_ in the site header, you can set the `title` field in `_data/header.yml`.
+
+### Site description
 
+You can change your site's description with the `description` field in `_config.yml`. If you want to override it for a particular page, you can set the `description` field in that page's frontmatter.
 
 ### Navigation
 
-This theme's navigation system is powerful and flexible. Named
-navigational lists live in your project's `_data/navigation.yml`,
-e.g.
+This theme's navigation system is powerful and flexible. Named navigational lists live in your project's `_data/navigation.yml`.
 
-By default all links are assumed to be internal to the site. You can add `external: true` to links that are external.
+By default all links are assumed to be internal to the site. You can add `external: true` to links that are external. You can also add `class: class-name` to add a class to a specific link.
 
 ```yml
 # _data/navigation.yml
+
 primary:
   - text: Documentation
     href: /docs/
   - text: Support
     href: /help/
-  - text: External link
+    class: highlight
+  - text: "18F"
     href: https://18f.gsa.gov
     external: true
 
   # link objects with a 'links' field will be presented as
-  # collapsible link lists. The 'links' field can either be a
-  # reference to another link list in this file, or a literal list.
+  # collapsible link lists. The 'links' field can either be
+  # a reference to another link list in this file, or
+  # a literal list.
+
   - text: Section title
     links: <links>
 ```
@@ -171,11 +153,19 @@ shared by different components, such as the [header](#header) and
 [footer](#footer). See the documentation for those components for
 more info.
 
+### Page title
+
+Set each page's title in its frontmatter:
+
+```
+---
+title: About us
+---
+```
 
 ### Page subnavigation
 
-If you're using the [page layout](#layout-page), each page may declare its own
-side navigation and subnavigation in its [front matter]:
+If you're using the [page layout](#layout-page), each page may declare its own side navigation and subnavigation in its front matter:
 
 ```md
 ---
@@ -186,22 +176,26 @@ subnav:
   - text: Section two
     href: '#section-two
 ---
+
 ## Section one
 
 ## Section two
 ```
 
-As with the [header](#header) and [footer](#footer), the `sidenav` field may
-either reference a common [navigation list](#navigation) from
-`_data/navigation.yml` (recommended) or be a literal list of links.
+As with the [header](#header) and [footer](#footer), the `sidenav` field may either reference a common [navigation list](#navigation) from `_data/navigation.yml` (recommended) or be a literal list of links.
+
+The `subnav` field should be used to link to sections _within_ the current page, because links to other pages will cause the linking page's side navigation to collapse when visited.
+
+`sidenav` is a key _into_ `_data/navigation.yml`. See the [navigation](#navigation) docs for more info.
 
-The `subnav` field should be used to link to sections _within_ the current
-page, because links to other pages will cause the linking page's side
-navigation to collapse when visited.
+A page's "current" or "active" state in the sidenav is determined by whether a link's `href` matches `page.url` or `page.permalink` for each page being rendered.
 
-**Pro tip:** Unless your Jekyll configuration specifies otherwise, the default
-Markdown formatter (Kramdown) will automatically generate predictable `id`
-attributes for your page headings and convert markdown like this:
+`subnav` is a list of links to display on this page under its own link in the side navigation.
+
+**Note that subnav link hrefs are not prefixed with
+`site.baseurl`** because this breaks hash links prefixed with `#`.
+
+**Pro tip:** Unless your Jekyll configuration specifies otherwise, the default Markdown formatter (Kramdown) will automatically generate predictable `id` attributes for your page headings and convert markdown like this:
 
 ```md
 ## Section one
@@ -223,6 +217,53 @@ redcarpet:
     - with_toc_data
 ```
 
+**Pro tip:** If you're like us and prefer your navigation sticky, you can add `sticky_sidenav: true` on [page](#layout-page), [project](#layout-project), and [team member](#layout-team-member) layouts to have the sidenav follow as you scroll.
+
+### Hero
+
+```yml
+hero: # optional
+  image: /path/to/image.jpg # optional
+  callout:
+    alt: Callout white text! # optional
+    text: The rest of the callout
+  button: # optional
+    text: The button text
+    href: /button-href/
+```
+
+### Tagline intro
+
+```yml
+# optional, but must be used in conjunction with 'intro', below
+tagline: A tagline for your page
+# also optional, but must be used with 'tagline', above
+intro: |
+  Some introductory text content.
+
+  This will be processed as **Markdown**.
+```
+
+### Graphics list
+
+```yml
+# an optional list of graphics to display before or after the content
+graphics:
+  - image:
+      # note the indentation here: graphics[n].image.src
+      src: /path/to/image.ext
+      alt: optional alt text
+    title: Optional graphic title, rendered as an <h3>
+    description: Graphic description text, processed as _Markdown_.
+
+# optional
+graphics_position: (before|after)
+```
+
+### Color configuration
+
+The default colors can be configured in the `_data/theme.yml` file. Other settings can be configured using USWDS theme settings. (See the [customization](#customization) section, below.)
+
 ### Search
 
 [Search.gov](https://search.gov/) is used for search and can be configured in `_config.yml`.
@@ -230,7 +271,7 @@ redcarpet:
 Before configuring your search you will need to create a search.gov account and set up your website
 with search.gov.
 
-After setting up your site on search.gov you can then add your `site handle` to the `config.yml`.
+After setting up your site on search.gov you can then add your `search_site_handle` to the `config.yml`.
 
 ### Analytics
 
@@ -245,29 +286,36 @@ You can add Google Analytics to your site by uncommenting the `google_analytics_
 
 #### Digital Analytics Program (DAP)
 
-You can add DAP to your site by uncommenting the `dap_agency` line and, if need be, replacing `GSA` with the appropriate agency key. For more information visit <https://www.digitalgov.gov/services/dap/>
+You can add DAP to your site by uncommenting the `dap_agency` line and, if need be, replacing `GSA` with the appropriate agency key.
+And optionally, `dap_subagency` may also be specified.
+For more information visit <https://www.digitalgov.gov/services/dap/>
 
 ```
 # Configuration for DAP, add your agency ID here:
 # dap_agency: GSA
+# dap_subagency: TTS
 ```
 
 ### Last modified date
 
-You can show the last date a page was last modified by uncommenting this line from the `footer.yml` data file.
-This will add the date right before the footer component and uses the `last-modified.html` include.
+You can show the last date a page was last modified by uncommenting this line from the `footer.yml` data file. This will add the date right before the footer component and uses the `last-modified.html` include.
 
 ```yml
 # Used to show the "Last updated" date and time;
 # last_updated: true
 ```
 
+### Anchor JS
+
+You can show an anchor link next to header tags by uncommenting this section from the `_config.yml` data file. This will add an anchor link after the header tag on the page and post layouts making ech header linkable. See https://github.com/bryanbraun/anchorjs for more information.
+
+```yml
+# anchor_js_targets: [h1, h2, h3, h4, h5, h6]
+```
+
 ## Assets
 
-The [stylesheet](_includes/styles.html) and [script](_includes/scripts.html)
-includes each incorporate the USWDS CSS and JS files if the corresponding
-`styles` and `scripts` lists aren't defined in your `_config.yml`. So unless
-you add one or both of those manually, your HTML will include the following:
+The [stylesheet](_includes/styles.html) and [script](_includes/scripts.html) includes each incorporate the USWDS CSS and JS files if the corresponding `styles` and `scripts` lists aren't defined in your `_config.yml`. So unless you add one or both of those manually, your HTML will include the following:
 
 ```html
 <!-- in the <head> -->
@@ -276,16 +324,12 @@ you add one or both of those manually, your HTML will include the following:
 <script src="/assets/uswds/js/uswds.min.js" async>
 ```
 
-Read more about customizing [stylesheets](#stylesheets) and [scripts](#scripts)
-below.
-
+Read more about customizing [stylesheets](#stylesheets) and [scripts](#scripts) below.
 
 ### Stylesheets
 
 As a general rule, all stylesheets are inserted in a layouts'
-`<head>`, which qualifies them as "render-blocking". Site
-stylesheets can be specified in `_config.yml` or a layout or page's
-[front matter] YAML in the following form:
+`<head>`, which qualifies them as "render-blocking". Site stylesheets can be specified in `_config.yml` or a layout or page's [front matter] YAML in the following form:
 
 ```yml
 styles:
@@ -297,7 +341,6 @@ styles:
 Stylesheets specified as objects (in the latter item above) must
 have an `href` property. The `media` defaults to `screen`.
 
-
 ### Scripts
 
 As a general rule, all scripts are inserted before a layouts'
@@ -313,14 +356,7 @@ scripts:
 ```
 
 Scripts specified as objects (in the latter item above) must have a `src`
-property. Scripts with `async: true` will get an `async` attribute, which tells
-the browser _not_ to let this script's loading block the execution of
-subsequent scripts. If the execution order of your scripts is **not**
-important, setting `async: true` may provide performance benefits to your
-users. (Conversely, if you don't know whether your scripts need to execute in a
-particular order, then you should not set `async: true` because it may prevent
-your scripts from running propertly.)
-
+property. Scripts with `async: true` will get an `async` attribute, which tells the browser _not_ to let this script's loading block the execution of subsequent scripts. If the execution order of your scripts is **not** important, setting `async: true` may provide performance benefits to your users. (Conversely, if you don't know whether your scripts need to execute in a particular order, then you should not set `async: true` because it may prevent your scripts from running propertly.)
 
 ### Asset load order
 
@@ -334,70 +370,20 @@ Both [stylesheets](#stylesheets) and [scripts](#scripts) can be configured
 1. Those configured at the page level (in the page's [front matter])
    will be loaded last.
 
-
 ## Customization
 
-You have two options for customizing the CSS: [Sass](#customizing-with-sass) or
-[CSS overrides](#customizing-with-css-overrides). Individual sites can also
-[selectively override](#overriding-includes-and-layouts) individual includes
-and layouts.
-
-
-### Customizing with Sass
-
-1. Create a [Sass][] (or SCSS) entry point that sets variables and then imports
-   the USWDS source files:
-
-    ```scss
-    ---
-    # assets/main.scss
-    ---
-    // set your variables or @import them here.
-
-    // at the very least, you should set the USWDS font and image paths
-    // to the correct paths relative to assets/main.css, like so:
-    $font-path: 'uswds/fonts';
-    $image-path: 'uswds/img';
-
-    @import 'uswds/all';
-    ```
-
-1. Change the path to your site's default stylesheet in your `_config.yml`:
-
-    ```yml
-    styles:
-      - /assets/main.css
-    ```
-
-All of the USWDS [SCSS source files](https://github.com/uswds/uswds/tree/master/src/stylesheets)
-are placed in the [_sass/uswds](_sass/uswds) directory and are available as
-Sass imports via `@import 'uswds/<path>';`. See the [Jekyll docs][Jekyll Sass]
-for more information about its Sass/SCSS support, and configuring its Sass
-renderer in your site's config.
-
+Customize the USWDS Jekyll theme with [USWDS theme settings files](https://designsystem.digital.gov/documentation/settings/), [USWDS design tokens](https://designsystem.digital.gov/design-tokens/), and custom Sass or CSS. You'll need to manually add these custom files to your Jekyll project into a couple specific locations.
 
-### Customizing with CSS overrides
+1. Find the **most current settings files** in the `_sass/settings` [folder of this theme](https://github.com/18F/uswds-jekyll/tree/update-uswds-2.0/_sass/settings). [Download these files with DownGit](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/18F/uswds-jekyll/tree/update-uswds-2.0/_sass/settings)
 
-1. Create a new CSS or Sass file that defines your customizations,
-   e.g.
+1. Copy these theme settings files to you project's `_sass/settings` directory. If this directory doesn't exist, create it.
 
-    ```scss
-    ---
-    # assets/uswds-overrides.scss
-    ---
-    .usa-header {
-      // overrides here
-    }
-    ```
+1. Edit these new settings files to customize your USWDS implementation, following the USWDS's [theme settings guidance](https://designsystem.digital.gov/documentation/settings/).
 
-1. Add the new stylesheet's path to your `_config.yml` _after_
-   `uswds.min.css`:
+1. Add any **custom CSS or Sass** to a folder called `_sass/custom/_uswds-theme-custom-styles.scss`. You can also use this file to import any additional Sass or CSS files your project needs. [Download this file from Github](https://raw.githubusercontent.com/18F/uswds-jekyll/update-uswds-2.0/_sass/custom/_uswds-theme-custom-styles.scss)
 
-    ```yml
-    styles:
-      - /assets/uswds/css/uswds.min.css
-      - /assets/uswds-overrides.css
-    ```
+You have two options for customizing the CSS: [Sass](#customizing-with-sass) or [CSS overrides (#customizing-with-css-overrides). Individual sites can also
+[selectively override](#overriding-includes-and-layouts) individual includes and layouts.
 
 ### Overriding includes and layouts
 
@@ -440,11 +426,10 @@ header data to come directly from the Jekyll configuration file
 `_includes/header.html` to look like this:
 
 ```html
-{% assign header = site.header %}
-{% include components/header--basic.html %}
+{% assign header = site.data.header %} {% include components/header--basic.html
+%}
 ```
 
-
 ### Header
 
 The [header.html include](_includes/header.html) sets the `header`
@@ -455,7 +440,6 @@ render the header's markup.
 
 See this repo's [header.yml](_data/header.yml) for more info.
 
-
 ### Footer
 
 The [footer.html include](_includes/footer.html) sets the `header`
@@ -466,18 +450,25 @@ render the footer's markup.
 
 See this repo's [footer.yml](_data/footer.yml) for more info.
 
-
 ## Layouts
 
 This theme provides the following layouts, which you can use by
 setting the `layout` [front matter] on each page, like so:
 
-```yaml
+```yml
 ---
 layout: name
 ---
+
 ```
 
+Supported (optional) front matter for page layouts.
+
+- [page navigation](#page-subnavigation)
+- [hero](#hero)
+- [tagline intro](#tagline-intro)
+- [graphics list](#graphics-list)
+
 ### `layout: default`
 
 This is the bare-bones USWDS layout, which does all of the
@@ -489,83 +480,197 @@ The default layout provides a layout [front matter] hook to add
 attributes to the `<main>` element. You can see how this works in
 the [page layout](_layouts/page.html#L3-L4).
 
-
 ### `layout: home`
 
 This layout implements the [home page
 template](https://designsystem.digital.gov/page-templates/landing/), which
 accommodates the following [front matter]:
 
+Check out the YAML front matter in the [home demo
+page](demo/home.html) for an example of how to structure it.
+
+### `layout: page`
+
+This layout implements the [document page
+template](https://designsystem.digital.gov/page-templates/docs/).
+
+See the [page demo page](demo/page.md) for an example of how this
+works, and see [\_data/navigation.yml](_data/navigation.yml) for how
+to structure named navigation data for your site.
+
+### `layout: post`
+
+This layout is identical to the layout `page` and is included to allow for easier site creation using `Jekyll new`.
+
+### `layout: project`
+
+This layout is used to show details for an individual project and uses the following front matter.
+
 ```yml
-hero: # optional
-  image: /path/to/image.jpg # optional
-  callout:
-    alt: Callout white text! # optional
-    text: The rest of the callout
-  button: # optional
-    text: The button text
-    href: /button-href/
+layout: project
+title: Title of project
+permalink: /projects/link-to-project/
+description: Project description.
+large_image: /path/to/image.ext
+small_image: /path/to/image.ext
+image_alt: The image alt text
+```
 
-# optional, but must be used in conjunction with 'intro', below
-tagline: A tagline for your page
-# also optional, but must be used with 'tagline', above
-intro: |
-  Some introductory text content.
+To show a listing of projects on a page add `{% include project-list.html %} to the page`
 
-  This will be processed as **Markdown**.
+### `layout: team-member`
 
-# an optional list of graphics to display before or after the content
-graphics:
-  - image:
-      # note the indentation here: graphics[n].image.src
-      src: /path/to/image.ext
-      alt: optional alt text
-    title: Optional graphic title, rendered as an <h3>
-    description: Graphic description text, processed as _Markdown_.
+This layout is used to show details for an individual team member and uses the following front matter.
 
-# optional
-graphics_position: (before|after)
+```yml
+layout: team-member
+permalink: /team/link-to-team-member/
+name: Team member name
+image: /path/to/image.ext
+job_title: Team member job title
+phone: 123-456-7890
+email: email@address.gov
 ```
 
-Check out the YAML front matter in the [home demo
-page](demo/home.html) for an example of how to structure it.
+To show a listing of team members on a page add `{% include team-list.html %} to the page`
 
+[sass]: http://sass-lang.com/guide
+[jekyll sass]: https://jekyllrb.com/docs/assets/#sassscss
+[front matter]: https://jekyllrb.com/docs/frontmatter/
 
-### `layout: page`
+## Migration
+
+### From [guides_style_18f](https://github.com/18F/guides-style)
+
+See [this example pull request](https://github.com/18F/before-you-ship/pull/458).
+
+### From from earlier versions
+
+**Note:** `uswds-jekyll` 5.x is only compatible with Jekyll 4.0 and higher.
+
+1. Update your `uswds-jekyll` gem in your project's Gemfile. Replace the current `gem 'uswds-jekyll'` line with:
+
+   ```ruby
+   gem 'uswds-jekyll', '~> 5.0'
+   ```
+
+   Then, in the terminal, run
+
+   ```sh
+   bundle update uswds-jekyll
+   ```
+
+1. Add any custom styles to `/_sass/custom/`
+1. `_sass` folder needs to be at the root level, not in assets.
+1. Convert manual values to tokenized values using the guidance on the [USWDS migration page](https://designsystem.digital.gov/documentation/migration/#spacing-units).
+1. Don't duplicate the `h1` in the body content of `page` template pages. (This is automatically inserted at the top with the content of `page.title`.)
+1. Check that certain data keys exist
+
+   ```
+   --> config.yml
+   styles:
+     [nothing unless adding additional stylesheets]
+
+   --> header.yml
+   type: [basic | basic-mega | extended | extended-mega]
+
+   --> footer.yml
+   type: [slim | default | big]
+
+   --> navigation.yml
+   sidenav-breakpoint: {{ breakpoint_token }}
+
+   --> theme.yml (examples)
+   colors:
+     usa-banner:
+       usa-banner-bg: 'base-lightest'
+       usa-banner-text: 'ink'
+       usa-banner-link: 'primary-dark'
+       usa-banner-link-hover: 'primary-darker'
+     header:
+       header-bg: 'white'
+       header-title: 'ink'
+       header-link: 'base'
+       header-link-hover: 'primary-dark'
+     alt-section:
+       bg-color: 'primary-darker'
+       header-color: 'accent-cool'
+       text-color: 'white'
+       link-color: 'base-lightest'
+       link-hover-color: 'white'
+     hero:
+       hero-bg: 'primary-darker'
+       hero-header: 'accent-cool'
+       hero-header-alt: 'white'
+       hero-text: 'white'
+       hero-link: 'accent-cool'
+       hero-button-bg: 'primary'
+       hero-button-text: 'white'
+     top-navigation:
+       top-nav-bg: 'white'
+       top-nav-link: 'base-dark'
+       top-nav-link-hover: 'primary'
+       top-nav-link-hover-bg: 'white'
+       top-nav-link-current: 'base-dark'
+       top-nav-dropdown-bg: 'primary-dark'
+       top-nav-dropdown-link: 'white'
+       top-nav-dropdown-link-hover-bg: 'transparent'
+     side-navigation:
+       side-nav-bg: 'transparent'
+       side-nav-link: 'ink'
+       side-nav-link-hover: 'primary-dark'
+       side-nav-link-hover-bg: 'base-lightest'
+       side-nav-link-current: 'primary-dark'
+     footer:
+       primary-footer-bg: 'base-lightest'
+       primary-footer-link: 'ink'
+       footer-bg: 'base-lighter'
+       footer-text: 'ink'
+       footer-link: 'ink'
+       footer-social-link: 'black-transparent-10'
+
+   ```
+
+1. Check that css is referencing `uswds-theme.css`
+
+## Development
 
-This layout implements the [document page
-template](https://designsystem.digital.gov/page-templates/docs/), and
-accommodates an optional side navigation. Supported [front matter]:
+To develop this theme and/or test it locally:
 
-* `sidenav` is a key _into_ `_data/navigation.yml`. See the
-  [navigation](#navigation) docs for more info.
+1. Clone this repo
 
-    A page's "current" or "active" state in the sidenav is
-    determined by whether a link's `href` matches `page.url` or
-    `page.permalink` for each page being rendered.
+1. Check the version of USWDS in `package.json` — update to the newest version if necessary, and sync its new files to the theme.
 
-* `subnav` is a list of links to display on this page under its own
-  link in the side navigation.
+   > `rake update`
 
-    **Note that subnav link hrefs are not prefixed with
-    `site.baseurl`** because this breaks hash links prefixed with
-    `#`.
+1. Start Jekyll to preview the effects of your changes. This will build the Jekyll site, watch the Sass files, and recompile the Sass when there are changes.
 
-See the [page demo page](demo/page.md) for an example of how this
-works, and see [_data/navigation.yml](_data/navigation.yml) for how
-to structure named navigation data for your site.
+   > `npm start`
 
-### `layout: post`
+   **or**
+
+   Create a new Jekyll project, follow the
+   [installation](#installation) instructions, then change your
+   `Gemfile` to point at the local clone of this repo:
 
-This layout is identical to the layout `page` and is included to allow for easier site creation using  `Jekyll new`.
+   ```ruby
+   gem 'uswds-jekyll', :path => '../path/to/uswds-jekyll'
+   ```
 
-### `layout: search-results`
+### Publish to Rubygems
 
-This layout is for search results and contains the `jekyll_pages_api_search_results`
-that renders the results into the `<main>` element. All of the other layouts "inherit" this one and
-provide other features in the content block.
+1. Update `spec.version = "NUMBER HERE"` in the uswds-jekyll.gemspec file to the version you want to publish
+1. Run `bundle install`
+1. Add a PR for the update and get it merged
+1. Run `bundle exec rake release`
+1. Add a GitHub release to the releases page with the same version number
+1. You should see the latest version here https://rubygems.org/gems/uswds-jekyll
 
+#### Scripts
 
-[Sass]: http://sass-lang.com/guide
-[Jekyll Sass]: https://jekyllrb.com/docs/assets/#sassscss
-[front matter]: https://jekyllrb.com/docs/frontmatter/
+- `start`: Starts the jekyll site
+- `setup-uswds`: Copies assets from the USWDS package to their theme locations, but running the following scipts, which can also be run separately:
+  - `sync-assets`: Copies assets to `assets/uswds`
+  - `sync-sass`: Copies Sass cource files to `_sass/uswds/src/`
+  - `sync-default-settings`: Copies default settings files to `_sass/uswds/settings`
+  - `sync-theme-settings`: Copies only theme settings files to `_sass/settings`