18F’s main website

This repository houses the 18F website. We use the U.S. Web Design System for the front end interface. The site is built and served through the Federalist platform.

Style and style guide

18f.gsa.gov extends the U.S. Web Design System and 18F Brand guidelines to create a style that is professional, unique, and informative. This relies on the uswds-jekyll theme to minimize the amount of custom styling and components of the site.

The style guide, located at 18f.gsa.gov/styleguide/ documents the patterns and components used to create this theme.

Add a blog post

See the blogpost example file for a template and instructions on how to create a new post.

Local development

Note: The Federalist platform does not support the use of a predefined SHOME environment variable which impacts the installation of the site's testing dependency pry (See the issue). In order to build the Federalist deployment and keep the tests working in CI, a Federalist specific gemfile (GemfileFederalist) was created to exclude the testing and development groups during install. The Federalist script in the package.json is run during the build time a creates a bundler config to install the GemfileFederalist dependencies and not the default Gemfile. Any updates to the production builds Gemfile should be included in the GemfileFederalist until a better fix is in place for the pry dependency or the Federalist platform.

Make sure you have Ruby 2.7.4 and Python 3.9 installed and active for the project directory. Python 3.7, 3.8, or 3.9 is required for some of the dependency builds.

Run each of the following steps to get the site up and running.

1. git clone [email protected]:18F/18f.gsa.gov
2. cd 18f.gsa.gov
3. bundle install
4. npm install
5. ./serve

To reduce the build time, instead of ./serve you can run ./serve-fast. This will eliminate all of the blog posts and the search index, but generates all other pages

You should be able to see the site at: http://127.0.0.1:4000/site/

NOTE: If you are using an M-series Mac (M1, M2, etc.), you may need to configure bundler to use special build flags for eventmachine. To do that, run:

bundle config --local build.eventmachine "--with-ldflags=\"-Wl,-undefined,dynamic_lookup\""

You may also have to run the bundle install step 2 or 3 times for everything to finish building.

Local development using docker

Using Docker can make dependencies management easier, but can also slow down your build time. You can find out more in this discussion.

To try this out on MacOS:

1. Install Docker Desktop via the GSA Self Service or download from their website.
2. Make sure Docker is running (you should see the whale icon in the taskbar or menu bar).
3. Open a termninal window (CMD+Space on Mac, Start > Run > "cmd" on Windows) and navigate into your project folder cd folder_name_with_code.
4. Run docker compose build to build the docker image and its dependencies.
5. Run docker compose up. Note: if you want to run a single command and bypass your Dockerfile for debugging purposes, you can do like so docker compose run app <COMMAND> (for instance, you can run bundle docker compose run app bundle install). Our site is large, so this could take awhile.
6. Visit http://localhost:4000/site/ in your browser. Make sure that you include the trailing slash.

If there was an error with the build, rebuild using the --no-cache option like so docker compose build --no-cache to avoid using the old version of the docker image.

Updating content

Upating styling

The site relies primarily on USWDS2 styles pulled in via the uswds-jekyll theme.

Please ensure that style updates are consistent with our brand's colors, typography, and iconography.

Per this, there are generally two main scss files:

• _sass/_uswds-theme-theme-settings.scss This stylesheet pulls in all of the USWDS2 theme variables that are set in the _sass/_theme directory. If you want to modify a style, try to make the change globally using the provided theme variables before creating a custom style.

• _sass/_uswds-theme-custom-styles.scss This stylesheet pulls in custom styling from the _sass/_components, _sass/templates, and _sass/styleguide directories.

• _sass/_components is a directory of 18f site specific components. Where possible USWDS2 components should be used in lieu of custom components, because they will be better maintained.

• _sass/templates is a directory of page specific stylesheets. Where possible, pages should use reusable site components over custom page layouts.

• _sass/_styleguide is a directory of stylesheets specifically for the /styleguide portion of the site.

Adding testimonials

Testimonials can be added as a compontent as long as an agency logo is place in the assets/img/agencies directory.

Images

Project page images

It really helps to have good pictures to help us highlight project work — but you might need a little more guidance about how to get pictures that will tell a story best. Here are some helpful tips:

If possible:

1. Image should relate to the project title, the department, or the process (in order of preference)
2. Show real users that benefit from this project
3. Show a screenshot from the project
4. Mix it up! Look at the current project list. Do you see too many of the same type of image (for example, mostly screenshots, mostly brainstorming sessions)

Consider accessibility and try to avoid images that:

• Are low-contrast
• Have wording on them

Consider the audience (government employees and potential partners!) and try to avoid images with the following:

• Sensitive subject material (for example, children when writing about Child Protective Services)
• Uninteresting subjects
• Super meta imagery (too much of a cognitive leap when relating to subject matter)

Size:

• Banner: Size 1300x866

Deployment

The site is a static website with HTML, CSS, and Javascript. Deployments are done through Federalist.

1. Federalist runs in its own organization and space in cloud.gov, which piggybacks on AWS GovCloud.
2. Federalist Admin.
3. Federalist responds to a webhook on GitHub and runs Jekyll to generate static web files and puts them in an S3 bucket.
4. We map 18f.gsa.gov URL to the S3 bucket.

Plugins

18f.gsa.gov is using several Ruby gems plugins:

Components

Featured posts

This component will showcase the first 3 posts of a given component.

History

A detailed history of the past work that went into developing this redesign can be found at 18F/beta.18f.gov.