Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update readme to improve customization instructions #208

Merged
merged 8 commits into from
Sep 16, 2020
Merged

Update readme to improve customization instructions #208

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3785643
Remove duplicate `from`
thisisdano Sep 16, 2020
5031248
FIx custom Sass location for migrations
thisisdano Sep 16, 2020
64a89f7
Improve customization docs
thisisdano Sep 16, 2020
dd6608b
Remove stylesheet override example
thisisdano Sep 16, 2020
80e576c
Remove manual line breaks
thisisdano Sep 16, 2020
a137852
Remove deleted TOC items
thisisdano Sep 16, 2020
b9c1e95
Edits for clarity and typos
thisisdano Sep 16, 2020
89bc5a0
Update README.md
afeld Sep 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 36 additions & 88 deletions README.md
View file
Open in desktop
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