{"id":14037190,"url":"https://github.com/cloud-gov/pages-uswds-jekyll","last_synced_at":"2025-07-27T05:30:49.879Z","repository":{"id":37847710,"uuid":"166146615","full_name":"cloud-gov/pages-uswds-jekyll","owner":"cloud-gov","description":"Reference implementation of USWDS 2.0 for Jekyll on Cloud.gov.  Demo -\u003e","archived":false,"fork":false,"pushed_at":"2024-08-01T23:42:09.000Z","size":2876,"stargazers_count":36,"open_issues_count":34,"forks_count":46,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-08-13T03:07:13.688Z","etag":null,"topics":["cloud-gov","cloud-gov-pages","federalist"],"latest_commit_sha":null,"homepage":"https://uswds-jekyll.pages.cloud.gov/","language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud-gov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-17T02:31:17.000Z","updated_at":"2024-06-08T02:36:11.000Z","dependencies_parsed_at":"2023-02-15T00:21:06.761Z","dependency_job_id":null,"html_url":"https://github.com/cloud-gov/pages-uswds-jekyll","commit_stats":null,"previous_names":[],"tags_count":4,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fpages-uswds-jekyll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fpages-uswds-jekyll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fpages-uswds-jekyll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fpages-uswds-jekyll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud-gov","download_url":"https://codeload.github.com/cloud-gov/pages-uswds-jekyll/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227762601,"owners_count":17816049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-gov","cloud-gov-pages","federalist"],"created_at":"2024-08-12T03:02:34.266Z","updated_at":"2024-12-02T16:32:22.581Z","avatar_url":"https://github.com/cloud-gov.png","language":"SCSS","funding_links":[],"categories":["SCSS"],"sub_categories":[],"readme":"# DEPRECATED - This repository is no longer in use and will not be maintained.\n\n# Pages + U.S. Web Design System + Jekyll\n\nThis [Jekyll theme](https://jekyllrb.com/docs/themes/) is developed using the [U.S. Web Design System v 2.0](https://v2.designsystem.digital.gov) and is focused on providing developers a starter kit and reference implementation for cloud.gov Pages websites.\n\nThis code uses the [Jekyll](https://jekyllrb.com) site engine and built with Ruby. If you prefer to use Javascript, check out [federalist-uswds-gatsby](https://github.com/18F/federalist-uswds-gatsby), which uses [Gatsby](https://gatsbyjs.org) site engine.\n\nThis project strives to be compliant with requirements set by [21st Century IDEA Act](https://www.meritalk.com/articles/senate-passes-idea-act/). The standards require that a website or digital service:\n\n- is accessible to individuals with disabilities;\n- has a consistent appearance;\n- does not duplicate any legacy websites (the legislation also requires agencies to ensure that legacy websites are regularly reviewed, removed, and consolidated);\n- has a search function;\n- uses an industry standard secure connection;\n- “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;”\n- allows for user customization; and\n- is mobile-friendly.\n\n## Comparison with [uswds-jekyll](https://github.com/18F/uswds-jekyll)\n\nBoth start off looking very similar, but differ in what use cases they are best for. Are you:\n\n- Wanting to have a starter template that you can highly customize?\n- Comfortable editing HTML and CSS source code?\n\nuse federalist-uswds-jekyll (this repository). If you:\n\n- Want to use a theme that you can set and forget\n- Are ok with sticking with the general look and feel provided\n\nuse uswds-jekyll.\n\n## Key Functionality\nThis repository contains the following examples and functionality:\n\n✅  Publish blog posts, press releases, announcements, etc. To modify this code, check out `blog/index.html`, which manages how the posts are listed. You should then check out `_layouts/post.html` to see how individual posts are structured.\n\n✅ Publish single one-off pages. Instead of creating lots of folders throughout the root directory, you should put single pages in `_pages` folder and change the `permalink` at the top of each page. Use sub-folders only when you really need to.\n\n✅  Publish data (for example: job listings, links, references), you can use the template `_layouts/data.html`. Just create a file in you `_pages` folder with the following options:\n\n```\n---\ntitle: Collections Page\nlayout: data\npermalink: /collections\ndatafile: collections\n---\n```\n\nThe reference to `datafile` referers to the name of the file in `_data/collections.yml` and loops through the values. Feel free to modify this as needed.\n\n✅  There are two different kinds of `pages`, one does not have a side bar navigation, and the other uses `_includes/sidenav.html`. You can enable this option by adding `sidenav: true` to your page front matter.\n\n```\n---\ntitle: Document with Sidenav\nlayout: page\nsidenav: true\npermalink: /document-with-sidenav\n---\n```\n\n✅ [Search.gov](https://search.gov) integration - Once you have registered and configured Search.gov for your site by following [these instructions](https://federalist.18f.gov/documentation/search/), add your \"affiliate\" and \"access key\" to `_config.yml`. Ex.\n\n```\nsearchgov:\n\n  # You should not change this.\n  endpoint: https://search.usa.gov\n\n  # replace this with your search.gov account\n  affiliate: federalist-uswds-example\n\n  # replace with your access key\n  access_key: xX1gtb2RcnLbIYkHAcB6IaTRr4ZfN-p16ofcyUebeko=\n\n  # this renders the results within the page instead of sending to user to search.gov\n  inline: true\n```\n\nThe logic for using Search.gov can be found in `_includes/searchgov/form.html` 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\n```\nsearchgov:\n  inline: false\n```\nin `_config.yml`.\n\n✅ [Digital Analytics Program (DAP)](https://digital.gov/services/dap/) integration - Once you have registered your site with DAP add your \"agency\" and optionally, `subagency` to `_config.yml` and uncomment the appropriate lines. Ex.\n\n```\ndap:\n  # agency: your-agency\n\n  # Optional\n  # subagency: your-subagency\n```\n\n✅ [Google Analytics](https://analytics.google.com/analytics/web/) integration - If you have a Google Analytics account to use, add your \"ua\" to `_config.yml` and uncomment the appropriate lines. Ex.\n\n```\nga:\n  # ua: your-ua\n```\n\n## How to edit\n- Non-developers should focus on editing markdown content in the `_posts` and `_pages` folder\n\n- We try to keep configuration options to a minimum so you can easily change functionality. You should review `_config.yml` to see the options that are available to you. There are a few values on top that you **need** to change. They refer to the agency name and contact information. The rest of `_config.yml` has a range of more advanced options.\n\n- The `assets/` folder stores your Javascript, CSS, images, and other media assets. Additional SASS partials should be added to the `_sass/` folder where they can be imported. USWDS assets are automatically copied into the `assets/` folder when running `jekyll serve` or `jekyll build`\n\n- If you look at `package.json` you will see that the `npm run federalist` command that will run when running on the Federalist platform.\n\n- Do not edit files in the `_site/` folder. These files are auto-generated, and any change you make in the folder will be overwritten.\n\n- To edit the look and feel of the site, you need to edit files in `_includes/` folder, which render key components, like the menu, side navigation, and logos.\n\n- `index.html` may not require much editing, depending on how you customize `hero.html` and `highlights.html`.\n\n- `_layouts/` may require the least amount of editing of all the files since they are primarily responsible for printing the content.\n\n- `blog/index.html` can be edited, but be careful. It will impact the pagination system for the posts. If you do edit the file, be prepared to edit `_config.yml`.  For example, you may need go change configurations for [jekyll-paginate-v2](https://github.com/sverrirs/jekyll-paginate-v2)\n\n- `search/index.html` is used by search.gov.\n\n## Getting Started\n\n### Easy mode\n\n#### From Federalist\nThis will create a copy of this repo in a Github repository of your choice and add it to your Federalist dashboard.\n\n- From [Federalist](https://federalistapp.18f.gov/sites) click the \"+ Add Site\" button.\n- Click the \"Use this template\" button for the appropriate template\n- Follow the instructions\n\n#### From Github\nThis will create a copy of this repo in a Github repository of your choice but you will need to add it your [Federalist dashboard](https://federalistapp.18f.gov/sites/new).\n\n- Click the \"Use this template\" button above or [here](https://github.com/18F/federalist-uswds-jekyll/generate).\n- Follow the instructions\n- Return to [Federalist](https://federalistapp.18f.gov/sites/new) and add the repository.\n\n### Hard mode\n\n#### With `npx` (requires node)\n    $ npx degit https://github.com/18F/federalist-uswds-jekyll#main \u003cdestination-folder\u003e\n    $ cd \u003cdestination-folder\u003e\n\n#### Push to your Github repository\n- [Create a new Github repository](https://help.github.com/en/github/getting-started-with-github/create-a-repo).\n- Follow the instructions form Github or\n```\n    $ git init\n    $ git symbolic-ref HEAD refs/heads/main\n    $ git add . \u0026\u0026 git commit -m 'Initial commit'\n    $ git remote add origin git@github.com:\u003cyour-org\u003e/\u003cyour-repo\u003e.git\n    (Make sure to replace `\u003cyour-org\u003e` and `\u003cyour-repo\u003e` above with the correct values)\n    $ git push -u origin main\n```\n\n### Installation for development\n    $ git clone https://github.com/18F/federalist-uswds-jekyll\n    $ cd federalist-uswds-jekyll\n\n### Running the application\n\n#### With locally installed `node` and `ruby`\n    $ npm install\n    $ bundle install\n    $ npm start\n    OR\n    $ bundle exec jekyll serve\n\nTo build but not serve the site, run `npm run build` or `bundle exec jekyll build`.\n\n#### With Docker\n    $ docker-compose run node npm install\n    $ docker-compose build\n    $ docker-compose up\n\nTo build but not serve the site, run:\n```\ndocker-compose run ruby bundle exec jekyll build\n```\n.\n\nNote that when built by Federalist, `npm run federalist` is used instead of\n`npm run build`.\n\nOpen your web browser to [localhost:4000](http://localhost:4000/) to view your\nsite.\n\n### Testing\n\n#### With locally installed `node` and `ruby`\n    $ npm test\n    OR\n    $ bundle exec htmlproofer _site; npx a11y '_site/**/*.html'\n\n#### With Docker\n    $ docker-compose run ruby bundle exec htmlproofer _site; npx a11y '_site/**/*.html'\n\n## Technologies you should be familiarize yourself with\n\n- [Jekyll](https://jekyllrb.com/docs/) - The primary site engine that builds your code and content.\n- [Front Matter](https://jekyllrb.com/docs/frontmatter) - The top of each page/post includes keywords within `--` tags. This is meta data that helps Jekyll build the site, but you can also use it to pass custom variables.\n- [U.S. Web Design System v 2.0](https://v2.designsystem.digital.gov)\n\n\n## Contributing\n\nSee [CONTRIBUTING](CONTRIBUTING.md) for additional information.\n\n## Public domain\n\nThis project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md):\n\n\u003e This project is in the public domain within the United States, and copyright\n\u003e and related rights in the work worldwide are waived through the [CC0 1.0\n\u003e Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).\n\u003e\n\u003e All contributions to this project will be released under the CC0 dedication.\n\u003e By submitting a pull request, you are agreeing to comply with this waiver of\n\u003e copyright interest.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-gov%2Fpages-uswds-jekyll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud-gov%2Fpages-uswds-jekyll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-gov%2Fpages-uswds-jekyll/lists"}