Federalist + U.S. Web Design System + Gatsby

This site is developed using the U.S. Web Design System v 2.0 and is focused on providing developers a starter kit and reference implementation for Federalist websites. You can view the preview deployed on Federalist.

This code uses the Gatsby framework and built with Javascript and React. If you prefer to use Ruby, check out federalist-uswds-jekyll, which uses Jekyll site engine.

This project assumes that you are comfortable editing source code. If you prefer to launch a website without editing any source code, checkout uswds-jekyll, which allows you to change the layout and content with configuration files.

This project strives to be compliant with requirements set by 21st Century IDEA Act. The standards require that a website or digital service:

• is accessible to individuals with disabilities;
• has a consistent appearance;
• does not duplicate any legacy websites (the legislation also requires agencies to ensure that legacy websites are regularly reviewed, removed, and consolidated);
• has a search function;
• uses an industry standard secure connection;
• “is designed around user needs with data-driven analysis influencing management and development decisions, using qualitative and quantitative data to determine user goals, needs, and behaviors, and continually test the website, web-based form, web-based application, or digital service to ensure that user needs are addressed;”
• allows for user customization; and
• is mobile-friendly.

🖐Previous Versions 🖐

If you're looking for the original starter that included a more integrated approach to using USWDS with React, it is still available here, but will not be maintained.

Features

✅ USWDS v2 javascript, styles, images, and fonts are included by default. Styles can be customized with either SASS or CSS in src/styles/index.scss.

✅ Publish blog posts using Markdown. Any markdown files in the src/blog-posts directory will be turned into pages at /blog/<path> in the application using the src/templates/blog-post.js template, where <path> is specified in the frontmatter of the file. An index of all posts will be displayed at /blog using the src/templates/blog.js template.

✅ Publish documentation pages using Markdown. Any markdown files in the src/documentation-pages directory will be turned into pages at /<path> in the application using the src/templates/documentation-page.js template, where <path> is specified in the frontmatter of the file. Side navigation for documentation pages can be controlled by setting sidenav: true or sidenav: false to your page front matter.

✅ Publish custom pages using React. Any javascript files in the src/pages directory will be turned into pages at /<filename>.html, where <filename> is the actualy name of the file.

✅ Customize SEO information for each page by adding the src/components/seo.js component to any page or template and providing the desired information. Ex. Home page.

✅ Search.gov integration - Once you have registered and configured Search.gov for your site by following these instructions, add your "affiliate" and "access key" to gatsby-config.js. Ex.

searchgov: {

  // You should not change this.
  endpoint: 'https://search.usa.gov',

  // replace this with your search.gov account
  affiliate: 'federalist-uswds-example',

  // replace with your access key
  access_key: 'xX1gtb2RcnLbIYkHAcB6IaTRr4ZfN-p16ofcyUebeko=',

  // this renders the results within the page instead of sending to user to search.gov
  inline: true,
}

The logic for using Search.gov can be found in the src/components/search-form.js component and supports displaying the results inline or sending the user to Search.gov the view the results. This setting defaults to "inline" but can be changed by setting searchgov: { inline: false } in gatsby-config.js.

✅ Digital Analytics Program (DAP) integration - Once you have registered your site with DAP add your "agency" and optionally, subagency to gatsby-config.js and uncomment the appropriate lines. Ex.

dap: {
    // agency: 'your-agency',

    // Optional
    // subagency: 'your-subagency',
},

✅ Google Analytics integration - If you have a Google Analytics account to use, add your "ua" to gatsby-config.js and uncomment the appropriate lines. Ex.

ga: {
    // ua: 'your-ua',
},

✅ Out-of-the-box performant caching strategy following Gatsby recommended practices via federalist.json. See Federalist Documentation for more information on federalist.json.

Getting Started

Easy mode

From Federalist

This will create a copy of this repo in a Github repository of your choice and add it to your Federalist dashboard.

• From Federalist click the "+ Add Site" button.
• Click the "Use this template" button for the appropriate template
• Follow the instructions

From Github

This will create a copy of this repo in a Github repository of your choice but you will need to add it your Federalist dashboard.

• Click the "Use this template" button above or here.
• Follow the instructions
• Return to Federalist and add the repository.

Hard mode

With npx (requires node)

$ npx degit https://github.com/18F/federalist-uswds-gatsby#main <destination-folder>
$ cd <destination-folder>

Push to your Github repository

• Create a new Github repository.
• Follow the instructions form Github or

    $ git init
    $ git symbolic-ref HEAD refs/heads/main
    $ git add . && git commit -m 'Initial commit'
    $ git remote add origin [email protected]:<your-org>/<your-repo>.git
    (Make sure to replace `<your-org>` and `<your-repo>` above with the correct values)
    $ git push -u origin main

Installation for development

$ git clone https://github.com/18F/federalist-uswds-gatsby
$ cd federalist-uswds-gatsby

Running the application

With locally installed node

$ npm install
$ npm run develop

To build but not serve the site, run npm run build.

With Docker

$ docker-compose run node npm install
$ docker-compose up

To build but not serve the site, run:

docker-compose run node npm run build

.

Note that when built by Federalist, npm run federalist is used instead of npm run build.

Open your web browser to localhost:8000 to view your site.

Note: You'll also see a second link: http://localhost:8000/___graphql. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the Gatsby tutorial.

Note that when built by Federalist, npm run federalist is used instead of the build script.

Technologies you should be familiarize yourself with

• Gatsby - The framework that does all the magic
• React - The view library
• GraphQL - The data layer used by Gatsby
• node - Javascript runtime
• npm - Javascript dependency manager
• U.S. Web Design System v 2.0

🎓 Learning Gatsby

Looking for more guidance? Full documentation for Gatsby lives on the website. Here are some places to start:

• For most developers, we recommend starting with our in-depth tutorial for creating a site with Gatsby. It starts with zero assumptions about your level of ability and walks through every step of the process.

• To dive straight into code samples, head to our documentation. In particular, check out the Guides, API Reference, and Advanced Tutorials sections in the sidebar.

Things to Note

• The Federalist script runs the Gatsby build with the --prefix-paths flag. This is necessary to make sure all internal internal links point to the correct path for preview deployments.
• Always use the Link component provided by Gatsby for internal links, see previous note.
• Importing USWDS images can be done straight from their local location in node_modules. See Banner.js for an example.
• This is built from the default Gatsby default starter, you can view the documentation there to see more of what is included.

Contributing

See CONTRIBUTING for additional information.

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

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.