Merge branch 'main' into db/add-breadcrumb-spacing-3057

.github/workflows/deploy-reusable.yml

@@ -0,0 +1,84 @@
+on:
+  workflow_call:
+    inputs:
+      github-sha:
+        required: true
+        type: string
+      github-run-id:
+        required: true
+        type: string
+      github-event-number:
+        required: false
+        type: string
+      matrix-name:
+        required: true
+        type: string
+      matrix-bucket:
+        required: true
+        type: string
+      matrix-config:
+        required: true
+        type: string
+    secrets:
+      aws-access-key-id:
+        required: true
+      aws-secret-access-key:
+        required: true
+jobs:
+  jekyll-deploy-reusable_workflow_job:
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ inputs.matrix-name }}
+      url: "https://${{ inputs.matrix-bucket }}"
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Use Node.js 16.x
+        uses: actions/setup-node@v2
+        with:
+          node-version: 16.x
+          cache: 'yarn'
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7.5 # Not needed with a .ruby-version file
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - run: yarn install
+      - run: yarn run build
+      - run: bundle exec jekyll build --config _config.yml,jekyll-configs/${{ inputs.matrix-config }} --baseurl /${{ inputs.github-event-number }}
+      - name: Make BUILD.txt file
+        # The -e flag enables the interpretation of the \n newline character
+        run: |
+          echo -e "REF=${{ inputs.github-sha }}\n\
+          BUILD_ID=${{ inputs.github-run-id }}\n\
+          BUILDTIME=$(date)" > _site/BUILD.txt
+      # We are taking these extra steps due to some differences between Jekyll and AWS S3.
+      # To access a .html file served from S3, the URL needs to have the .html extension.
+      # We're removing the extension to make the URLs prettier.
+      # More context:
+      #   https://simpleit.rocks/ruby/jekyll/tutorials/having-pretty-urls-in-a-jekyll-website-hosted-in-amazon-s3/
+      - name: Remove .html extension on non-index files
+        run: |
+          find _site/ -type f ! -iname 'index.html' -iname '*.html' \
+          -print0 | while read -d $'\0' f; do mv "$f" "${f%.html}"; done
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.aws-access-key-id }}
+          aws-secret-access-key: ${{ secrets.aws-secret-access-key }}
+          aws-region: "us-gov-west-1"
+      - name: Sync extensionless html files with correct type
+        run: |
+          aws s3 sync _site s3://${{ inputs.matrix-bucket }} \
+          --acl public-read \
+          --delete \
+          --exclude "storybook/*" \
+          --exclude "*.*" \
+          --content-type "text/html"
+      - name: Sync remaining files
+        run: |
+          aws s3 sync _site s3://${{ inputs.matrix-bucket }} \
+          --acl public-read \
+          --delete \
+          --exclude "*" \
+          --include "*.*" \
+          --exclude "storybook/*"

.github/workflows/deploy.yml

@@ -8,7 +8,7 @@ jobs:
   deploy:
     strategy:
       matrix:
-        environment: [{ bucket: dev-design.va.gov, config: dev.yml }, { bucket: staging-design.va.gov, config: staging.yml }, { bucket: design.va.gov, config: prod.yml }]
+        environment: [{ bucket: staging-design.va.gov, config: staging.yml }, { bucket: design.va.gov, config: prod.yml }]
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
@@ -41,7 +41,7 @@ jobs:
       run: |
         find _site/ -type f ! -iname 'index.html' -iname '*.html' \
         -print0 | while read -d $'\0' f; do mv "$f" "${f%.html}"; done
-    - uses: aws-actions/configure-aws-credentials@v1
+    - uses: aws-actions/configure-aws-credentials@v4
       with:
         aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
         aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

.github/workflows/preview.yml

@@ -0,0 +1,25 @@
+name: Preview
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+
+jobs:
+  dev-deploy-preview:
+    strategy:
+      matrix:
+        environment: [{ name: development, bucket: "dev-design.va.gov/${{ github.event.number }}", config: dev.yml }]
+    uses: ./.github/workflows/deploy-reusable.yml
+    with: 
+      github-sha: ${{ github.sha }}
+      github-run-id: ${{ github.run_id }}
+      github-event-number: ${{ github.event.number }}
+      matrix-name: ${{ matrix.environment.name }}
+      matrix-bucket: ${{ matrix.environment.bucket }}
+      matrix-config: ${{ matrix.environment.config }}
+    secrets:
+      aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

README.md

@@ -90,9 +90,25 @@ While `vets-design-system-documentation` is running and make further updates to
 
 1. Commit this along with any updates to the documentation site and submit a PR.
 
-## Deploying
+## Deployments
 
-Merges into `main` will automatically be deployed to `dev-design.va.gov`. Production is automatically deployed every weekday at 2pm. Deploys are executed by creating a release of vets-website via Jenkins. You can track the deployment in the Slack channel, #design-system.
+Merges into `main` will automatically deploy to production `design.va.gov` after CI checks have completed. 
+
+### Previewing Pull Requests
+
+When a PR is created, a preview of those changes will be available after the [Preview workflow](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/.github/workflows/preview.yml) has completed. There will be a "View deployment" button visible that will launch the preview environment when clicked:
+
+![The "view deployment" button on a pull request](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/src/images/readme/pr-view-deployment-button.png?raw=true)
+
+The preview link can also be accessed directly using this pattern: `https://dev-design.va.gov/PR_NUMBER`. For example, `https://dev-design.va.gov/3435` where `3435` is the unique PR number visible in the PR title.
+
+If the preview has stopped working (for example if you're only seeing a 403 Forbidden error or similar), re-run the preview workflow by clicking "Details" next to the Preview check:
+
+![A list of PR checks with an arrow pointing to the details link for the Preview workflow](https://raw.githubusercontent.com/department-of-veterans-affairs/vets-design-system-documentation/refs/heads/main/src/images/readme/pr-checks-preview-details.png)
+
+Then click the "Re-run all jobs" button at the top of the page:
+
+![The "Re-run all jobs" button for running a Github workflow again](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/src/images/readme/re-run-workflow-button.png?raw=true)
 
 ## Additional Testing
 

jekyll-configs/dev.yml

@@ -1 +1,2 @@
-storybook_path: "/storybook"
+url: "https://dev-design.va.gov" # Base hostname & protocol for the preview site
+storybook_path: "/storybook"

src/_content-style-guide/error-messages/engagement.md

@@ -6,7 +6,7 @@ title: Engagement messages
 intro-text: Nudges the user to enter or update data in the system. It can be initiated by either the system or another user.
 ---
 
-***Note:** See [Error Messages](/patterns/help-users-to/recover-from-errors#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See [Error Messages]({{ site.baseurl }}/patterns/help-users-to/recover-from-errors#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ## Prompt to complete a task or enter data
 

src/_content-style-guide/messaging-dictionary.md

@@ -17,7 +17,7 @@ anchors:
 
 Alerts the user of important system-related issues or status. It’s initiated by the system and it’s not a result of the user’s actions.
 
-***Note:** See [content style guide](/content-style-guide/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See [content style guide]({{ site.baseurl }}/content-style-guide/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ### Scheduled downtime notice scenarios
 
@@ -42,7 +42,7 @@ Alerts the user of important system-related issues or status. It’s initiated b
 
 Nudges the user to enter or update data in the system. It can be initiated by either the system or another user.
 
-***Note:** See [content style guide](/content-style-guide/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See [content style guide]({{ site.baseurl }}/content-style-guide/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ### Prompt to complete a task or enter data
 
@@ -55,7 +55,7 @@ Nudges the user to enter or update data in the system. It can be initiated by ei
 
 Appears when the user tries to access an item that’s not available to them. It may be because the record has been deleted, the user doesn’t have access, etc.
 
-***Note:** See [content style guide](/content-style-guide/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See [content style guide]({{ site.baseurl }}/content-style-guide/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ### System downtime
 
@@ -110,7 +110,7 @@ Variations in messaging will be contingent on:
 
 The application’s response when the user is interacting with it. The majority of create, read, update, delete (CRUD) actions will result in feedback messaging.
 
-***Note:** See [content style guide](/content-style-guide/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
+***Note:** See [content style guide]({{ site.baseurl }}/content-style-guide/messaging-error-messages#next-step-calls-to-action) for guidance on when to consider adding instruction to call the VA.gov help desk or other "next-step" call to action.*
 
 ### Task completion success/failure
 

src/_foundation/layout/index.md

@@ -4,7 +4,6 @@ permalink: /foundation/layout/
 title: Layout
 sub-pages:
   - sub-page: Flexbox grid
-  - sub-page: Float grid
   - sub-page: Page layouts
 ---
 
@@ -16,9 +15,9 @@ sub-pages:
 
 {% include _site-in-this-section.html %}
 
-## Grids
+## Flexbox grid
 
-We have two types of grids. One is the float grid (whereas "float" refers to the `float` CSS property) provide by the U.S. Web Design System.  The other grid is a flexbox grid (which refers to the `flexbox` CSS spec) that provides more design flexibility and options to use with responsive design. A similar flexbox grid will be offered in the U.S. Web Design System version 2.0.
+The flexbox grid (which refers to the `flexbox` CSS spec) provides more design flexibility and options to use with responsive design.
 
 ## Page layouts
 

src/_includes/_side-nav.html

@@ -44,7 +44,7 @@
                               {% assign is-current = false %}
                             {% endif %}
                           <li>
-                            <a class="{% if is-current == true %}usa-current{%- endif -%}" href="{{p.permalink }}{{ item.sub-page | slugify }}">
+                            <a class="{% if is-current == true %}usa-current{%- endif -%}" href="{{site.baseurl}}{{p.permalink }}{{ item.sub-page | slugify }}">
                               {{ item.sub-page }}
                               {%- if include.name == 'components' -%}
                                 {%- include _site-side-nav-status.html components=sortedPages component=item.sub-page parent=p.title -%}

src/_includes/_site-in-this-section.html

@@ -8,7 +8,7 @@
     <dd role="definition" class="site-in-this-section__definition">
       <a
         class="site-in-this-section__link"
-        href="{{ page.url }}{{ item.sub-page | slugify }}"
+        href="{{site.baseurl}}{{page.permalink }}{{ item.sub-page | slugify }}"
       >
         {{ item.sub-page }}
       </a>

src/_includes/header.html

@@ -50,7 +50,7 @@
       <div class="site-header__utility-links">
         <div id="search-container" class="site-search-container">
           <i class="fas fa-search search-icon"></i>
-          <form action="/results" method="get" id="search-form" class="search-form">
+          <form action="{{ site.baseurl }}/results" method="get" id="search-form" class="search-form">
           <input type="search" class="site-search-container__input" id="search-input" placeholder="Search..." aria-label="Search" name="query" autocomplete="off">
           </form>
           <ul id="results-container" class="site-search-results" role="listbox"></ul>
@@ -64,7 +64,7 @@
 
 <div id="mobile-search-container" class="site-search-container site-seach-container--mobile">
   <i class="fas fa-search search-icon search-icon--mobile"></i>
-  <form action="/results" method="get" id="mobile-search-form" class="search-form">
+  <form action="{{ site.baseurl }}/results" method="get" id="mobile-search-form" class="search-form">
     <input type="search" class="site-search-container__input vads-u-max-width--none" id="mobile-search-input" placeholder="Search..." aria-label="Search" name="query" autocomplete="off">
   </form>
   <ul id="mobile-results-container" class="site-search-results site-search-results--mobile" role="listbox"></ul>