Skip to content

Commit

Permalink
Merge pull request #208 from 18F/dw-update-readme
Browse files Browse the repository at this point in the history 
Update readme to improve customization instructions
  • Loading branch information
@afeld
afeld authored Sep 16, 2020
2 parents d7034dd + 89bc5a0 commit f3e214e
Showing 1 changed file with 36 additions and 88 deletions.
124 changes: 36 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,6 @@ This is a [Jekyll theme](https://jekyllrb.com/docs/themes/) for the
- [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)
1. [Components](#components)
- [Header](#header)
Expand Down Expand Up @@ -77,8 +75,7 @@ You will need to restart your Jekyll server to see the effects.
gem 'uswds-jekyll'
```

1. Set the `theme` in your site's Jekyll configuration,
`_config.yml`:
1. Set the `theme` in your site's Jekyll configuration, `_config.yml`:

```yml
theme: uswds-jekyll
Expand All @@ -96,8 +93,7 @@ You will need to restart your Jekyll server to see the effects.

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. 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
Expand All @@ -106,9 +102,7 @@ To reference a specific version of this theme:

## 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
of each component.
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 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.

Expand Down Expand Up @@ -148,10 +142,7 @@ primary:
links: <links>
```
This scheme allows you to define navigational elements that can be
shared by different components, such as the [header](#header) and
[footer](#footer). See the documentation for those components for
more info.
This scheme allows you to define navigational elements that can be shared by different components, such as the [header](#header) and [footer](#footer). See the documentation for those components for more info.
### Page title
Expand Down Expand Up @@ -192,8 +183,7 @@ A page's "current" or "active" state in the sidenav is determined by whether a l

`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 `#`.
**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:

Expand All @@ -207,8 +197,7 @@ into:
<h2 id="section-one">Section one</h2>
```

If you're using Redcarpet, you will need to configure it to enable
the `with_toc_data` extension in your `_config.yml`, like so:
If you're using Redcarpet, you will need to configure it to enable the `with_toc_data` extension in your `_config.yml`, like so:

```yml
markdown: redcarpet
Expand Down Expand Up @@ -286,9 +275,7 @@ 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.
And optionally, `dap_subagency` may also be specified.
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:
Expand Down Expand Up @@ -328,8 +315,7 @@ Read more about customizing [stylesheets](#stylesheets) and [scripts](#scripts)
### 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:
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:
```yml
styles:
Expand All @@ -338,15 +324,11 @@ styles:
media: (screen|print|all) # optional
```
Stylesheets specified as objects (in the latter item above) must
have an `href` property. The `media` defaults to `screen`.
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'
`</body>`, which prevents them from blocking the rendering of your
page's content. Scripts can be specified in `_config.yml` or a
layout or page's [front matter] YAML in the following form:
As a general rule, all scripts are inserted before a layouts' `</body>`, which prevents them from blocking the rendering of your page's content. Scripts can be specified in `_config.yml` or a layout or page's [front matter] YAML in the following form:
```yml
scripts:
Expand All @@ -355,8 +337,7 @@ scripts:
async: true # optional
```
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.)
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.)
### Asset load order
Expand All @@ -372,30 +353,24 @@ Both [stylesheets](#stylesheets) and [scripts](#scripts) can be configured
## Customization
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.
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 place USWDS settings and custom Sass into a couple specific locations for the theme to find them.
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. **Settings:** Add custom USWDS settings to `_sass/_uswds-theme-settings.scss`. Settings control the USWDS output. See all available settings in the [USWDS settings documentation](https://designsystem.digital.gov/documentation/settings/). We recommend adding only your modified settings to the `_uswds-theme-settings.scss` file.
1. Copy these theme settings files to you project's `_sass/settings` directory. If this directory doesn't exist, create it.
To see an example of all the settings available to USWDS, see the files [in the USWDS GitHub repo](https://github.com/uswds/uswds/tree/develop/src/stylesheets/theme). The repo splits settings into multiple files. If you want to copy and mimic that structure, download the repo files using a tool like [DownGit](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/uswds/uswds/tree/develop/src/stylesheets/theme). Then add them to the `_sass/` directory and `@import` them from `_uswds-theme-settings.scss`.
1. Edit these new settings files to customize your USWDS implementation, following the USWDS's [theme settings guidance](https://designsystem.digital.gov/documentation/settings/).
Whether you add only individual settings variables or import from multiple files, `_uswds-theme-settings.scss` needs to be the entry point.
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)
1. **Custom Sass and variables:** Add any custom CSS or Sass to `_sass/_uswds-theme-custom-styles.scss`. You can use this custom styles file to `@import` any _additional_ Sass or CSS files your project needs, as long as any additional files exist in the `/_sass` directory.
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.
Custom Sass loads after the USWDS and default Sass, so you can use it to override the defaults. Individual sites can also [selectively override](#overriding-includes-and-layouts) individual includes and layouts.
### Overriding includes and layouts
Any [include](_includes) or [layout](_layouts) can be overridden by
your site by placing a file with the same name into your site's
`_includes` or `_layouts` directory. For instance:
- To change how [stylesheets](#stylesheets) are loaded or
referenced, you can create your own `_includes/styles.html`,
which will subsequently change how stylesheets are loaded in all
layouts that inherit from the USWDS [default layout](#layout-default).
- You can change how the side navigation is rendered (but not which
data it receives) in the [page layout](#layout-page) by creating
your own `_includes/sidenav.html`.
Expand All @@ -406,24 +381,13 @@ your site by placing a file with the same name into your site's
## Components
For some [USWDS components](https://designsystem.digital.gov/components/),
there are two different files that control how data is passed to
For some [USWDS components](https://designsystem.digital.gov/components/), there are two different files that control how data is passed to
the template:
1. `components/{component}.html` is the low-level template that
assumes a similarly named global template variable. For
instance, the header component operates on the `header` template
variable.
1. `{component}.html` is the "concrete" implementation of the
component that sets the appropriate global variable then
includes the low-level template.
This separation allows you to override either of the component
includes in your own Jekyll site without having to re-implement
either the high- or low-level logic. For instance, if you want your
header data to come directly from the Jekyll configuration file
(`_config.yml`) rather than `_data/header.yml`, you can override
`_includes/header.html` to look like this:
1. `components/{component}.html` is the low-level template that assumes a similarly named global template variable. For instance, the header component operates on the `header` template variable.
1. `{component}.html` is the "concrete" implementation of the component that sets the appropriate global variable then includes the low-level template.
This separation allows you to override either of the component includes in your own Jekyll site without having to re-implement either the high- or low-level logic. For instance, if you want your header data to come directly from the Jekyll configuration file (`_config.yml`) rather than `_data/header.yml`, you can override `_includes/header.html` to look like this:
```html
{% assign header = site.data.header %} {% include components/header--basic.html
Expand All @@ -432,28 +396,20 @@ header data to come directly from the Jekyll configuration file
### Header
The [header.html include](_includes/header.html) sets the `header`
template variable to `site.data.header`, the value of which is set
in your Jekyll project's `_data/header.yml` file. Then it includes
[components/header.html](_includes/components/header.html) to
render the header's markup.
The [header.html include](_includes/header.html) sets the `header` template variable to `site.data.header`, the value of which is set in your Jekyll project's `_data/header.yml` file. Then it includes [components/header.html](_includes/components/header.html) to 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`
template variable to `site.data.footer`, the value of which is set
in your Jekyll project's `_data/footer.yml` file. Then it includes
[components/footer.html](_includes/components/footer.html) to
The [footer.html include](_includes/footer.html) sets the `header` template variable to `site.data.footer`, the value of which is set in your Jekyll project's `_data/footer.yml` file. Then it includes [components/footer.html](_includes/components/footer.html) to
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:
This theme provides the following layouts, which you can use by setting the `layout` [front matter] on each page, like so:
```yml
---
Expand All @@ -471,32 +427,22 @@ Supported (optional) front matter for page layouts.
### `layout: default`
This is the bare-bones USWDS layout, which does all of the
basic page scaffolding then drops the page content into the
`<main>` element. All of the other layouts "inherit" this one and
provide other features in the content block.
This is the bare-bones USWDS layout, which does all of the basic page scaffolding then drops the page content into the `<main>` element. All of the other layouts "inherit" this one and provide other features in the content block.
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).
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]:
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.
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/).
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.
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`
Expand Down Expand Up @@ -544,7 +490,7 @@ To show a listing of team members on a page add `{% include team-list.html %} to
See [this example pull request](https://github.com/18F/before-you-ship/pull/458).
### From from earlier versions
### From earlier versions
**Note:** `uswds-jekyll` 5.x is only compatible with Jekyll 4.0 and higher.
Expand All @@ -560,8 +506,10 @@ See [this example pull request](https://github.com/18F/before-you-ship/pull/458)
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. If you have an existing `_sass` folder, it needs to move to the root level, and out of any directory like `/assets`.
1. Add or move any custom styles or variables to `/_sass/_uswds-theme-custom-styles.scss`.
If you have multiple custom styles files, add them to the `/_sass` directory and `@import` them from `_uswds-theme-custom-styles.scss`.
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
Expand Down

0 comments on commit f3e214e

Please sign in to comment.