diff --git a/README.md b/README.md index 0ec9915..829127c 100644 --- a/README.md +++ b/README.md @@ -1,196 +1,19 @@ -# 11ty-uswds-template +# 10x mutual aid -## Why this project +A prototype website for the 10x project bringing mutual aid to underserved communities for post disaster rebuilding -This is an [11ty](https://www.11ty.dev/) static site generator (SSG) template using [U.S. Web Design System v 3.0 (USWDS)](https://designsystem.digital.gov/) and is focused on providing developers a starter template and reference implementation for Federalist/Cloud.gov Pages websites. +## Running the prototype locally -This 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: +Requires Node.js and npm -- 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. +1. Install dependencies with `npm install` +2. Running a local server with `npm run dev` +3. Visit [http://localhost:8080/](http://localhost:8080/) -## Key Functionality -This repository contains the following examples and functionality: -✅ 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 `_includes/layouts/post.html` to see how individual posts are structured. +## Deploying the prototype -✅ 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. +The software is deployed to Cloud.gov Pages automatically upon commiting code to the `main` Git branch. -✅ 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. +The most recent deployment is [here](https://federalist-fc42b3e8-1d7d-4650-b068-c0c57c55dcfd.sites.pages.cloud.gov/site/gsa-tts/10x-mutual-aid/). -``` ---- -title: Document with Sidenav -layout: layout/page -sidenav: true -permalink: /document-with-sidenav ---- -``` - -✅ [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 `_data/site.yml`. 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 `_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 -``` -searchgov: - inline: false -``` -in `_data/site.yml`. - -✅ [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 `_data/site.yml` and uncomment the appropriate lines. Ex. - -``` -dap: - # agency: your-agency - - # Optional - # subagency: your-subagency -``` - -✅ [Google Analytics](https://analytics.google.com/analytics/web/) integration - If you have a Google Analytics account to use, add your "ua" to `_data/site.yml` and uncomment the appropriate lines. Ex. - -``` -ga: - # ua: your-ua -``` - -## Getting Started - -### Installing Dependencies - -`npm install` - -TODO - -### Running a Dev Instance - -`npm run dev` - -TODO - -## Netlify CMS - - - -### Config - -The Netlify CMS can be configured in [`/admin/config.yml`](./admin/config.yml) and you will update the -`repo` key to be your Github organization and repository name. - -```yml -backend: - name: github - repo: / - base_url: https://federalistapp.18f.gov - auth_endpoint: external/auth/github - preview_context: federalist/build - branch: master - use_graphql: true -``` - -### Running Locally - -You can run the Netlify CMS locally to more easily customize and troubleshoot the CMS to you content. -We provide comments in the [`/admin/config.yml`](./admin/config.yml) instructing you how to change the `backend` values from your production site to the local development. - -> *Note: Make sure to not commit and push the config with the `backend` set for local develop to Github or -else you will break your production site's Netlify CMS. - -```yml -# Local development backend -backend: - name: git-gateway -local_backend: true -``` - -Once you [`/admin/config.yml`](./admin/config.yml) is set to local development, you run `npm run dev:cms` to -serve as a development authentication server. - -## How To - -### Adding Collections - -TODO - -### Adding Static Data - -TODO - -### Creating links - -For preview links generated on the platform, we automatically set the `pathPrefix` in the [`.eleventy.js`](/.eleventy.js) file base on the `BASEURL` environment variable. We use the built-in 11ty filter for `url` to properly append the prefix path for the linked page. When adding new links, use the following syntax: - -```liquid -Link to My Dir -``` - -See the [11ty docs](https://www.11ty.dev/docs/filters/url/) - -### Referencing Images - -All of your images will be stored in the `_img/` directory. To reference your images in your templates you can use the `shortcodes` built into the template. - -For referencing an image without a style class, you will pass the template shortcode the image's source path and the alternative image name in that order. ie: - -``` -{% image "_img/my-image.png" "My PNG Image Alternative Name" %} -``` - -For referencing an image with a style class, you will pass the template shortcode the image's source path, class names, and the alternative image name in that order. ie: - -``` -{% image_with_class "_img/my-image.png" "img-class another-class" "My PNG Image Alternative Name" %} -``` - -### Referencing USWDS Sprite Icons - -USWDS has sprite icons available for use. Here is the [list of icons](https://designsystem.digital.gov/components/icon/) available when using the sprite shortcode `uswds_icon` in the template. The following example is how you can reference the icon in a template. - -``` -{% uswds_icon "" %} -``` - -### Expanding SCSS Styles - -CSS and SASS can be added or imported into the `styles/styles.scss`. You can also use [USWDS Design Tokens](https://designsystem.digital.gov/design-tokens/) in the `styles/themes` files to update colors, fonts, and layout to fit your site's branding. This template uses [esbuild](https://esbuild.github.io/)and [autoprefixer](https://github.com/postcss/autoprefixer) to bundle your SASS/CSS and fingerprint the files in the site build. - -### Adding custom Javascript - -Javascript can be added to the admin UI or site UI by adding or importing code into the `js/admin.js` or `js/app.js` files respectively. This template uses [esbuild](https://esbuild.github.io/) to bundle your javascript and fingerprint the files in the site build. - -### Customizing 11ty - -TODO - -## Contributing - -See [CONTRIBUTING](CONTRIBUTING.md) for additional information. - -## Public domain - -This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md): - -> 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](https://creativecommons.org/publicdomain/zero/1.0/). -> -> 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.