Update readme

CMSgov · Feb 25, 2025 · 7b8a76a · 7b8a76a
1 parent db04538
commit 7b8a76a
Show file tree

Hide file tree

Showing 2 changed files with 168 additions and 74 deletions.
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -3,40 +3,45 @@ GEM
   specs:
     addressable (2.8.7)
       public_suffix (>= 2.0.2, < 7.0)
-    bigdecimal (3.1.8)
+    base64 (0.2.0)
+    bigdecimal (3.1.9)
     colorator (1.1.0)
-    concurrent-ruby (1.3.3)
+    concurrent-ruby (1.3.5)
+    csv (3.3.2)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
     eventmachine (1.2.7)
-    ffi (1.17.0-arm64-darwin)
-    ffi (1.17.0-x86_64-darwin)
-    ffi (1.17.0-x86_64-linux-gnu)
+    ffi (1.17.1-arm64-darwin)
+    ffi (1.17.1-x86_64-darwin)
+    ffi (1.17.1-x86_64-linux-gnu)
     forwardable-extended (2.6.0)
-    google-protobuf (4.27.2-arm64-darwin)
+    google-protobuf (4.29.3-arm64-darwin)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.27.2-x86_64-darwin)
+    google-protobuf (4.29.3-x86_64-darwin)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.27.2-x86_64-linux)
+    google-protobuf (4.29.3-x86_64-linux)
       bigdecimal
       rake (>= 13)
     http_parser.rb (0.8.0)
-    i18n (1.14.5)
+    i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    jekyll (4.3.3)
+    jekyll (4.4.1)
       addressable (~> 2.4)
+      base64 (~> 0.2)
       colorator (~> 1.0)
+      csv (~> 3.0)
       em-websocket (~> 0.5)
       i18n (~> 1.0)
       jekyll-sass-converter (>= 2.0, < 4.0)
       jekyll-watch (~> 2.0)
+      json (~> 2.6)
       kramdown (~> 2.3, >= 2.3.1)
       kramdown-parser-gfm (~> 1.0)
       liquid (~> 4.0)
-      mercenary (>= 0.3.6, < 0.5)
+      mercenary (~> 0.3, >= 0.3.6)
       pathutil (~> 0.9)
       rouge (>= 3.0, < 5.0)
       safe_yaml (~> 1.0)
@@ -46,14 +51,15 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-redirect-from (0.16.0)
       jekyll (>= 3.3, < 5.0)
-    jekyll-sass-converter (3.0.0)
-      sass-embedded (~> 1.54)
+    jekyll-sass-converter (3.1.0)
+      sass-embedded (~> 1.75)
     jekyll-sitemap (1.4.0)
       jekyll (>= 3.7, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    kramdown (2.4.0)
-      rexml
+    json (2.10.1)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liquid (4.0.4)
@@ -68,21 +74,19 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.3.2)
-      strscan
-    rouge (4.3.0)
+    rexml (3.4.1)
+    rouge (4.5.1)
     safe_yaml (1.0.5)
-    sass-embedded (1.77.8-arm64-darwin)
-      google-protobuf (~> 4.26)
-    sass-embedded (1.77.8-x86_64-darwin)
-      google-protobuf (~> 4.26)
-    sass-embedded (1.77.8-x86_64-linux-gnu)
-      google-protobuf (~> 4.26)
-    strscan (3.1.0)
+    sass-embedded (1.85.1-arm64-darwin)
+      google-protobuf (~> 4.29)
+    sass-embedded (1.85.1-x86_64-darwin)
+      google-protobuf (~> 4.29)
+    sass-embedded (1.85.1-x86_64-linux-gnu)
+      google-protobuf (~> 4.29)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    unicode-display_width (2.5.0)
-    webrick (1.8.1)
+    unicode-display_width (2.6.0)
+    webrick (1.9.1)
 
 PLATFORMS
   arm64-darwin-23

diff --git a/README.md b/README.md
@@ -3,90 +3,189 @@
 This Ruby program builds the [ab2d.cms.gov](https://ab2d.cms.gov/) website via [Jekyll](https://jekyllrb.com/) and [U.S. Web Design System (USWDS)](https://designsystem.digital.gov/).
 
 ## Requirements
+> [!NOTE]
+> This repository assumes development on MacOS. If you're using Windows, some installation steps may be different.
 
-- [Ruby](https://www.ruby-lang.org/en/)
-- [Node.js (v20 or higher)](https://nodejs.org/en/download/)
+- [Homebrew](https://brew.sh/)
+- [Ruby](https://www.ruby-lang.org/en/) 
+- [Node.js](https://nodejs.org/en/download/) (v20 or higher required)
 - [npm](https://www.npmjs.com/get-npm)
 
-> [!NOTE]
-> Since there isn't a robust way to manange USWDS as a Ruby dependency, this repository uses two package dependency management tools: `npm` for JavaScript, and `gem` for Ruby.
-
-## Architecture
+## Installation
 
-This Jekyll site doesn't use a gem-based theme. All assets, layouts, includes, and stylesheets are contained within the repo.
+### Step 1: Install Homebrew
+> [!NOTE]
+> If you already have Homebrew on your machine, you can skip this step.
 
-It also doesn't use the [bundled Sass converter](https://jekyllrb.com/docs/configuration/sass/). Any unintentional Sass munging is avoided since all styles are precompiled via [`uswds-compile`](https://github.com/uswds/uswds-compile), USWDS's recommended set of [Gulp](https://gulpjs.com/) functions for copying the static assets and transforming Sass into CSS.
+Follow the installation process [found here](https://brew.sh/).
 
-USWDS assets are compiled during local development, isolating the Node.js environment so that it's not part of the build or deploy process. Only Ruby/Jekyll is required in the build process.
+You can confirm Homebrew is installed on your machine by running the following in your terminal:
 
-This architecture gives us the simplicity of Jekyll's plain-text content management (Markdown), build, and deploy; and the ability to compile a customized design system using [USWDS `$theme-` settings](https://designsystem.digital.gov/documentation/settings/).
+```sh
+brew -v
+```
 
-## Local development
+(You may need to close and reopen your terminal window)
 
-### Install and use pre-commit
+### Step 2: Install `pre-commit`
 
-Anyone committing to this repository must install [pre-commit](https://pre-commit.com/) and use the pre-commit hook to lower the likelihood that secrets will be exposed.
+> [!IMPORTANT]
+> Anyone committing to this repository must install [pre-commit](https://pre-commit.com/) and use the pre-commit hook to reduce the risk of exposing secrets.
 
-#### Step 1: Install pre-commit
+#### Install pre-commit
 
-You can install pre-commit using the MacOS package manager Homebrew:
+To install pre-commit, run the following in your terminal:
 
 ```sh
 brew install pre-commit
 ```
 
-Other installation options can be found in the [pre-commit documentation](https://pre-commit.com/#install).
-
-#### Step 2: Install the hooks
+#### Implement the pre-commit hook
 
-Run the following command to install the gitleaks hook:
+Run the following command to install the "gitleaks" hook:
 
 ```sh
 pre-commit install
 ```
 
 This will download and install the pre-commit hooks specified in `.pre-commit-config.yaml`.
 
-### Running the Jekyll server
+### Step 3: Install Ruby
+
+Using Jekyll requires Ruby to be installed on your system. We use `chruby` to make it easier to switch between Ruby versions. Due to limitations with our deployment process, the maximum version of Ruby we use is `v3.2.6`.
+
+Install `chruby` and `ruby-install` by running the following:
 
-The following command will run the Jekyll server and watch for changes:
+```sh
+brew install chruby ruby-install
+```
+
+Then, install Ruby v3.2.6 by running:
 
 ```sh
-bundle exec jekyll serve --livereload
+ruby-install ruby 3.2.6
 ```
 
-You can view the site at `http://localhost:4000/` and LiveReload will automatically reload your browser when files are modified.
+You can verify your installation by running: 
+```sh
+ruby -v
+```
 
-### Compiling USWDS styles and scripts
+(You may need to close and reopen your terminal window)
 
-> [!NOTE]
-> You only need to run the Gulp tasks when making changes to the design system. You can just run the Jekyll server when editing pages, components, or content.
+You should see something like: 
+```
+ruby 3.2.6 (2024-10-30 revision 63aeb018eb) ... 
+```
+
+### Step 4: Install Node.js and npm
 
-Install the `uswds-compile` and `uswds` dependencies:
+USWDS and other JavaScript packages require `npm` which comes with Node.js
+
+You can install this manually from the [Node.js website](https://nodejs.org/en/download/) or with Homebrew by running:
+
+```sh
+brew install node
+```
+
+You can verify the installation by running:
+
+```sh
+node -v
+npm -v
+```
+
+Your node version should be at least `v20`.
+
+### Step 5: Install Jekyll and Bundler
+
+Once Ruby is installed, install Jekyll and Bundler
+
+```sh
+gem install jekyll bundler
+```
+
+Verify your installation by running:
+
+```sh
+jekyll -v
+```
+
+You should see:
+
+```
+jekyll 4.4.1
+```
+
+### Step 6: Install Jekyll dependencies
+
+Install Jekyll dependencies via `Bundler` by running: 
+```sh
+bundle install
+```
+
+### Step 7: Install USWDS & other JavaScript dependencies
+
+Run the following:
 
 ```sh
 npm install
 ```
 
-Compile and update USWDS to copy files to the `./assets/uswds` directory:
+## Local Development
+
+Once you've gone through the installation process you should be able to run the site locally.
+
+### Running the Site
+
+Run the following command to start the Jekyll server and watch for changes to your SCSS and JS assets:
 
 ```sh
-npx gulp updateUswds
+npm run dev
 ```
 
-Or you can run the following command (in parallel with the Jekyll server) and Gulp will watch for changes to files in the `./_uswds_sass` directory and recompile the USWDS assets:
+You can view the site at `http://localhost:4000/`.
+
+### Compiling USWDS styles and scripts seperately
+
+You can run the following command to compile your assets without running the Jekyll server:
 
 ```sh
-npx gulp watch
+npm run assets:build
 ```
 
-#### USWDS Icons
+Alternatively, you can run the following to watch for changes as you modify your source files:
+
+```sh
+npm run assets:serve
+```
+
+### Running Jekyll seperately
+
+> [!WARNING]
+> Be careful running these scripts seperately. These scripts will only build the Jekyll site with the compiled assets. If you've made changes to your source CSS and JS files, those changes will not be captured in these scripts.
+
+You can also run Jekyll seperately with the following commands.
+
+To run the Jekyll server and automatically react to changes in your source files, run:
+
+```sh
+npm run jekyll:serve
+```
+
+Or, to build the Jekyll site without watching for changes, run:
+
+```sh
+npm run jekyll:build
+```
+
+## USWDS Icons
 
 Over 2K icons get compiled when you run the Gulp tasks. Woah! But every individual icon file is not tracked and committed.
 
 All of the `usa-icons` are packaged into a sprite, which should be preferred when possible:
 
-```
+```html
 <svg class="usa-icon" role="img">
   <use xlink:href="{{ '/assets/uswds/img/sprite.svg#arrow_forward' | relative_url }}"></use>
 </svg>
@@ -122,32 +221,23 @@ For specific customizations that cannot be achieved at the theme level, USWDS in
 
 If custom styles must be written, they should added to `_uswds-theme-custom-styles.scss`, where you can leverage [USWDS design tokens](https://designsystem.digital.gov/design-tokens/), variables, mixins, and functions.
 
-### Accessibility tests ([Pa11y](https://pa11y.org/))
+## Local accessibility testing
 
 The `.pa11yci` config file defines [Axe](https://github.com/dequelabs/axe-core) and [HTML_CodeSniffer](https://squizlabs.github.io/HTML_CodeSniffer/) accessibilty tests for WCAG 2 Level AA conformance that should be run during local development:
 
-Install Pa11y CI:
+### Run tests for every page in the sitemap
 
-```sh
-npm install -g pa11y-ci
-```
+In order to run accessibility tests, make sure the site is running locally. Then, you can run: 
 
-Run tests for every page in the sitemap:
 ```sh
-pa11y-ci --sitemap http://localhost:4000/sitemap.xml
+npm run pa11y
 ```
 
 Pa11y is configured to `includeWarnings` (not just errors) for more thorough compliance. However, some warning result codes are ignored for the following reasons:
 
 - `color-contrast` — [Pa11y reports false positives](https://github.com/pa11y/pa11y/issues/633) when axe can't determine the contrast ratio for certain elements.
-- `WCAG2AA.Principle1.Guideline1_3.1_3_1.H48` — `<p>` or `<div>` with more than one link is assumed as navigation to be marked up as a list
-- `WCAG2AA.Principle1.Guideline1_4.1_4_3.[G…].BgImage` — text and all covered parts of background image (hero gradient) need high contrast
-- `WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.Empty` — In-page Navigation JS inserts empty anchors (with IDs but without a href or link text)
 
 And some elements are hidden from testing:
 
 - `.usa-overlay` — area behind mobile nav has a fixed position which triggers a "scrolling in two dimensions" error
-- `.usa-in-page-nav__heading` — although heading structure is not logically nested, there's an [exception for fixed page sections](https://www.w3.org/WAI/tutorials/page-structure/headings/)
-
-> [!NOTE]
-> [Pa11y](https://pa11y.org/) can be further configured to run on each build, deploy, pull request, etc. This should be added to any the CI/CD setup.
+- `.usa-in-page-nav__heading` — although heading structure is not logically nested, there's an [exception for fixed page sections](https://www.w3.org/WAI/tutorials/page-structure/headings/)