OTHER License
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.
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:
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.
β
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
.
This will create a copy of this repo in a Github repository of your choice and add it to your Federalist dashboard.
This will create a copy of this repo in a Github repository of your choice but you will need to add it your Federalist dashbord.
npx
(requires node)$ npx degit https://github.com/18F/federalist-uswds-gatsby#main <destination-folder>
$ cd <destination-folder>
$ 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
$ git clone https://github.com/18F/federalist-uswds-gatsby
$ cd federalist-uswds-gatsby
node
$ npm install
$ npm run develop
To build but not serve the site, run npm run build
.
$ 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.
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.
--prefix-paths
flag. This is necessary to make sure all internal internal links point to the correct path for preview deployments.Link
component provided by Gatsby for internal links, see previous note.node_modules
. See Banner.js for an example.See CONTRIBUTING for additional information.
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.