Add search functionality using Pagefind

.github/workflows/deploy.yml

@@ -8,7 +8,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  build_and_deploy:
+  build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -44,17 +44,47 @@ jobs:
       - name: "Sync Donor Info"
         run: cd content/donate && ./sync_donors.sh
 
-      - name: "Build and deploy website"
-        if: github.repository_owner == 'bevyengine'
+      - name: "Build Website"
         uses: shalzz/[email protected]
         env:
-          PAGES_BRANCH: gh-pages
+          BUILD_ONLY: true
           BUILD_DIR: .
-          TOKEN: ${{ secrets.CART_PAT }}
+
+      - name: "Search (1/3): Setup Node.js"
+        uses: actions/setup-node@v4
+
+      # See: https://github.com/CloudCannon/pagefind/issues/675#issuecomment-2267210534
+      - name: "Search (2/3): Change `public` Permissions"
+        run: echo "$(whoami):$(id -gn)" | xargs -I {} sudo chown -R {} public
+
+      - name: "Search (3/3): Build Index"
+        run: npx --yes pagefind --output-path public/pagefind
+
+      - name: Upload GitHub Pages Artifact
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: public/
 
       # Caches output of generate-assets for use in ci.yml
       - name: Update generate-assets cache
         uses: actions/cache/save@v4
         with:
           path: content/assets
           key: assets-${{ steps.date.outputs.date }}-${{ hashFiles('generate-assets/**/*.rs', 'generate-assets/Cargo.toml', 'generate-assets/generate_assets.sh') }}
+
+  deploy:
+    if: github.repository_owner == 'bevyengine'
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        with:
+          token: ${{ secrets.CART_PAT }}

.gitignore

@@ -10,6 +10,7 @@ content/community/people/
 content/community/donate/
 static/assets/examples/
 static/processed_images/
+static/pagefind/
 
 # Tools
 target/

README.md

@@ -21,3 +21,29 @@ A local server should start and you should be able to access a local version of
 ### Assets, Errors, and Examples pages
 
 These pages need to be generated in a separate step by running the shell scripts in the `generate-assets`, `generate-errors`, and `generate-wasm-examples` directories. On Windows, you can use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) or [git bash](https://gitforwindows.org/).
+
+## Search Index
+
+We use [Pagefind](https://pagefind.app) for the search functionality.
+
+### Configuration
+
+Which pages to index, category assignment and the weight is configured in `/templates/macros/pagefind.html`.
+Note that the category names must be reflected when instancing `SearchCategories` in `/static/search.mjs`.
+
+Pagefind can be tweaked (ignore content, change weights…) at page and element level by using `data-pagefind-*` HTML attributes.
+
+The default configuration for the Pagefind CLI is defined in `/pagefind.yml`.
+
+### Local Development
+
+To generate the index for local development, download the [Pagefind binary](https://github.com/CloudCannon/pagefind/releases) in the project root and the run:
+
+```sh
+rm -rf public
+zola build
+./pagefind --write-playground
+```
+
+This will create the `/static/pagefind` folder which contains the index and JS library.
+You can access `http://127.0.0.1:1111/pagefind/playground/` to debug search issues.

pagefind.yml

@@ -0,0 +1,6 @@
+site: public
+output_path: static/pagefind
+exclude_selectors:
+  - ".tree-menu"
+  - ".example__back"
+  - ".example__github"

sass/_mixins.scss

@@ -1,3 +1,19 @@
+@mixin backdrop($z-index) {
+  visibility: hidden;
+  position: fixed;
+  inset: 0px;
+  z-index: $z-index;
+  background-color: var(--backdrop-color);
+  cursor: pointer;
+  opacity: 0.0;
+  transition: opacity $duration * 2;
+}
+
+@mixin backdrop-visible() {
+  visibility: visible;
+  opacity: 1.0;
+}
+
 @mixin card() {
   display: block;
   overflow: hidden;

sass/_utils.scss

@@ -1,5 +1,5 @@
 .hidden {
-  display: none;
+  display: none !important;
 }
 
 // Visual outline on focused elements, for accessibility

sass/_vars.scss

@@ -1,3 +1,5 @@
+@use "sass:color";
+
 // Typography
 $size-body: 16px; // Usual browser default size
 $size-body-mobile: 14px; // Size for mobile
@@ -25,6 +27,8 @@ $duration: 250ms;
 $z-layout-header: 800;
 $z-main-menu-backdrop: 900;
 $z-main-menu: 1000;
+$z-search-backdrop: 1100;
+$z-search: 1200;
 
 // General
 $max-width: 1200px;
@@ -42,13 +46,45 @@ $border-radius: 10px;
 // the `sass:color` package to derive new colors. If a color is not going to be
 // used to derive a new color, then CSS vars should be used instead.
 //
-// See PR: https://github.com/bevyengine/bevy-website/pull/1953
 // See Relative Colors support: https://caniuse.com/css-relative-colors
+//
+// To revert:
+// - Original PR: https://github.com/bevyengine/bevy-website/pull/1953
+// - `.search-category`: https://github.com/bevyengine/bevy-website/pull/1935/commits/30d94f6e9316b03d6741fbdfb4ea493f06485482
+// - `.search-result`: https://github.com/bevyengine/bevy-website/pull/1935/commits/0e0069784f93ab27273384ced13833657c73459e
 $color-neutral-17: #2c2c2d;
+$color-neutral-40: #666;
 $color-neutral-93: #ececec;
 $color-black: #000;
 $color-white: #fff;
 
+$color-dark-search-category-default-bg: $color-neutral-40;
+$color-dark-search-category-book-bg: #537134;
+$color-dark-search-category-examples-bg: #885d26;
+$color-dark-search-category-migrations-bg: #2b5e77;
+$color-dark-search-category-errors-bg: #953562;
+$color-dark-search-category-news-bg: #2c5580;
+$color-dark-search-category-contribute-bg: #78527e;
+
+$color-light-search-category-book-bg: #5b8b2c;
+$color-light-search-category-examples-bg: #b96f0e;
+$color-light-search-category-migrations-bg: #455f6b;
+$color-light-search-category-news-bg: #2c65a2;
+
+// TODO: Remove when CSS Relative Colors are available
+@mixin hack-search-category-computed-colors($category, $color) {
+  --search-category-#{$category}-bg-hover-color: #{color.adjust($color, $lightness: 4%)};
+  --search-category-#{$category}-border-color: #{color.adjust($color, $lightness: 10%)};
+  --search-category-#{$category}-text-color: #{color.change($color, $lightness: 90%)};
+}
+
+// TODO: Remove when CSS Relative Colors are available, check: `_search-category.scss`
+@mixin hack-search-category-modifier-vars($category) {
+  --bg-hover-color: var(--search-category-#{$category}-bg-hover-color);
+  --border-color: var(--search-category-#{$category}-border-color);
+  --text-color: var(--search-category-#{$category}-text-color);
+}
+
 // CSS Vars
 :root {
   // Typography
@@ -67,7 +103,7 @@ $color-white: #fff;
   --color-neutral-33: #555;
   --color-neutral-33b: #535353;
   --color-neutral-36: #59595e;
-  --color-neutral-40: #666;
+  --color-neutral-40: #{$color-neutral-40};
   --color-neutral-42: #6b6b6b;
   --color-neutral-45: #737373;
   --color-neutral-50: #808080;
@@ -141,6 +177,8 @@ $color-white: #fff;
   --asset-version-select-border-color: var(--color-neutral-22);
   --asset-version-select-border-hover-color: var(--color-neutral-42);
 
+  --backdrop-color: #{rgba($color-black, 0.2)};
+
   --bevy-instance-canvas-color: var(--color-neutral-18);
   --bevy-instance-text-shadow-color: var(--color-black);
   --bevy-instance-progress-track-color: var(--color-neutral-33);
@@ -165,6 +203,8 @@ $color-white: #fff;
   --button-pink-bg-hover-color: #954c72;
   --button-pink-border-color: #ba789b;
   --button-pink-text-color: var(--color-neutral-93);
+
+  --button-square-color: var(--color-neutral-93);
   --button-square-bg-color: #{rgba($color-neutral-93, 0.05)};
 
   --callout-caution-accent-color: #e82f5a;
@@ -329,6 +369,44 @@ $color-white: #fff;
   --people-role-maintainer-color: rgb(242, 103, 255);
   --people-role-sme-color: rgb(80, 200, 50);
 
+  --search-bg-color: var(--color-neutral-13);
+  --search-clear-icon-color: var(--color-neutral-93);
+  --search-border-color: var(--color-neutral-17);
+  --search-input-bg-color: var(--color-neutral-18);
+  --search-input-border-color: var(--color-neutral-22);
+  --search-input-color: var(--color-neutral-93);
+  --search-no-results-color: var(--color-neutral-75);
+  --search-tip-color: var(--color-neutral-67);
+
+  --search-category-default-bg-color: #{$color-dark-search-category-default-bg};
+  --search-category-default-bg-hover-color: #{rgba($color-white, 0.05)};
+  --search-category-border-color: var(--color-neutral-27);
+  --search-category-text-color: var(--color-neutral-67);
+  --search-category-text-hover-color: var(--color-white);
+  --search-category-book-bg-color: #{$color-dark-search-category-book-bg};
+  --search-category-examples-bg-color: #{$color-dark-search-category-examples-bg};
+  --search-category-migrations-bg-color: #{$color-dark-search-category-migrations-bg};
+  --search-category-errors-bg-color: #{$color-dark-search-category-errors-bg};
+  --search-category-news-bg-color: #{$color-dark-search-category-news-bg};
+  --search-category-contribute-bg-color: #{$color-dark-search-category-contribute-bg};
+
+  --search-category-default-border-color: #{color.adjust($color-dark-search-category-default-bg, $lightness: 10%)};
+  --search-category-default-text-color: #{color.change($color-dark-search-category-default-bg, $lightness: 90%)};
+  @include hack-search-category-computed-colors(book, $color-dark-search-category-book-bg);
+  @include hack-search-category-computed-colors(examples, $color-dark-search-category-examples-bg);
+  @include hack-search-category-computed-colors(migrations, $color-dark-search-category-migrations-bg);
+  @include hack-search-category-computed-colors(errors, $color-dark-search-category-errors-bg);
+  @include hack-search-category-computed-colors(news, $color-dark-search-category-news-bg);
+  @include hack-search-category-computed-colors(contribute, $color-dark-search-category-contribute-bg);
+
+  --search-result-bg-color: #{rgba($color-black, 0.15)};
+  --search-result-bg-hover-color: #{rgba($color-white, 0.04)};
+  --search-result-title-color: var(--color-white);
+  --search-result-hash-sign-color: var(--color-neutral-75);
+  --search-result-excerpt-color: var(--color-neutral-53);
+  --search-result-excerpt-term-bg-color: var(--color-white);
+  --search-result-excerpt-term-color: var(--color-neutral-82);
+
   --scrollbar-thumb-color: #{rgba($color-white, 0.2)};
 
   --sponsors-name-color: var(--color-neutral-59);
@@ -470,6 +548,36 @@ $color-white: #fff;
 
     --scrollbar-thumb-color: #{rgba($color-black, 0.2)};
 
+    --search-bg-color: var(--color-neutral-93);
+    --search-clear-icon-color: var(--color-neutral-13);
+    --search-border-color: var(--color-neutral-69);
+    --search-input-bg-color: var(--color-neutral-97);
+    --search-input-border-color: var(--color-neutral-82);
+    --search-input-color: var(--color-neutral-13);
+    --search-no-results-color: var(--color-neutral-40);
+    --search-tip-color: var(--color-neutral-40);
+
+    --search-category-default-bg-hover-color: #{rgba($color-black, 0.05)};
+    --search-category-border-color: var(--color-neutral-67);
+    --search-category-text-color: var(--color-neutral-33);
+    --search-category-text-hover-color: var(--color-black);
+    --search-category-book-bg-color: #{$color-light-search-category-book-bg};
+    --search-category-examples-bg-color: #{$color-light-search-category-examples-bg};
+    --search-category-migrations-bg-color: #{$color-light-search-category-migrations-bg};
+    --search-category-news-bg-color: #{$color-light-search-category-news-bg};
+
+    @include hack-search-category-computed-colors(book, $color-light-search-category-book-bg);
+    @include hack-search-category-computed-colors(examples, $color-light-search-category-examples-bg);
+    @include hack-search-category-computed-colors(migrations, $color-light-search-category-migrations-bg);
+    @include hack-search-category-computed-colors(news, $color-light-search-category-news-bg);
+
+    --search-result-bg-color: #{rgba($color-white, 0.15)};
+    --search-result-bg-hover-color: #{rgba($color-black, 0.04)};
+    --search-result-title-color: var(--color-black);
+    --search-result-hash-sign-color: var(--color-neutral-50);
+    --search-result-excerpt-term-bg-color: var(--color-black);
+    --search-result-excerpt-term-color: var(--color-neutral-33);
+
     --table-border-color: var(--color-neutral-75);
     --table-header-bg-color: var(--color-neutral-82);
     --table-header-color: var(--color-neutral-22);

sass/components/_button-square.scss

@@ -3,6 +3,12 @@
 
   position: relative;
   cursor: pointer;
+  color: var(--button-square-color);
+
+  * {
+    // Don't capture events on sub-elements
+    pointer-events: none;
+  }
 
   &:hover {
     &:before {

sass/components/_header.scss

@@ -64,13 +64,17 @@
   &__cta {
     flex-shrink: 0;
 
-    &:not(:last-child) {
-      margin-right: 8px;
+    &--search {
+      @media #{$bp-phone-landscape-down} {
+        display: none;
+      }
     }
 
     &--github {
       @include flex-center;
 
+      margin-left: 12px;
+
       img {
         height: 30px;
         width: auto;

sass/components/_icon.scss

@@ -20,6 +20,7 @@
     ("chevron-right", 9),
     ("github", 24),
     ("pencil", 19),
+    ("search", 24),
     ("times", 16),
   );
 

sass/components/_main-menu-backdrop.scss

@@ -1,20 +1,9 @@
 .main-menu-backdrop {
-  visibility: hidden;
-  position: fixed;
-  top: 0px;
-  left: 0px;
-  width: 100%;
-  height: 100%;
-  z-index: $z-main-menu-backdrop;
-  background-color: var(--main-menu-backdrop-color);
-  cursor: pointer;
-  opacity: 0;
-  transition: opacity $duration * 2;
+  @include backdrop($z-main-menu-backdrop);
 }
 
 @include state-checked("mobile-menu") {
   .main-menu-backdrop {
-    visibility: visible;
-    opacity: 1;
+    @include backdrop-visible(); 
   }
 }

sass/components/_main-menu.scss

@@ -82,7 +82,6 @@
     &__header {
       display: flex;
       align-items: center;
-      justify-content: space-between;
       padding-left: $padding;
       height: var(--layout-header-height);
       background-color: var(--layout-header-bg-color);
@@ -94,6 +93,10 @@
       }
     }
 
+    &__logo {
+      margin-right: auto;
+    }
+
     &__page-menu-switch {
       display: none;
       padding: $padding $padding 0 $padding;