chore: small styles and quality of life improvements (#2058)

* fix / improve vite config file

styles source maps in dev are very helpful during development

`css.preprocessorOptions.scss.additionalData` needs to be a string or a
function, so having array was wrong and did't work with `devSourcemap`
setting.

modern scss compiler api is just a suggested by sass and legacy api will
be sooner or later removed.

* improve jekyll-dev config

adding `_assets/styles/` directory to excluded allows vite to handle
sass files compilation and when developing won't cause jekyll to hard
refresh page whenever styles changes and allow vite to hot reload just
styles

* fix navbar for 404 pages

`this.sidebarButton` is null for some pages, like 404

* cleanup and improve prism.js

1. `vite` is minifying scripts and styles during production builds so it
   was unnecessary to import minified versions. Importing minified
   versions was causing that it was harded to debug styles/scripts during
   developement
2. plugin `prism-show-language` was not used, and it was imported before
   `prism-toolbar` which was causing it was not even working and logging
   warninng message in console
3. we are not using `prism-tomorrow` theme
4. moving out copy icon html elements and formated it with new lines
   made it a little bit easier to read

* removed unused prism-ghcolors.scss

* fix and improve sidebar.js script

1. `expandActiveGroup` was incorrectly closing groups which were nested
   more than one level - this commit fixes that
2. smoth scrolling to sidebar element was broken when there was not
   enough scroll height to show the active link in the middle. In such
   cases it was moving down global page scroll with the missing height value
3. small refactoring of `setActiveLink` method

* fix copy to clipboard button in code blocks

1. now instead of being visible on the left side of the string with a
   type of code (`yaml`, `sh` etc.) when you are hovering over code
   block it's hiding the type string and showing always in the same
   position - top right corner. It was broken before for blocks which
   types were longer than `sh`.
2. added simple fade for the button on hover
3. fixed position of sting "Copied!" when clicked

* fixed line numbers in code blocks

when code block had more than 9 lines it was broken as line numbers 10+ had
not enough padding on the left - not it looks fine for line numbers up
to 99

* stick version selector and search bar even when scroll is present

Now, even if sidebar is longer than the screen height, version selector
and search bar will always be present at the top.

This commit also removes this weird unnecessary empty space at the
bottom of the sidebar.

* improve pages with version alerts

1. version alert block now has the same width to the rest of page
2. huge empty space between version alert and the page header was
   shrinked so it looks more natural

* improve dev related make targets and remove unnecessary files

1. Instead of using raw vite we can use netlify, which we are still
   using otherwise. It also have result that specified by us redirects
   in `_common-redirects` and _redirects` files work.
2. Using netlify instead of vite with its scripts under `bin` directory
   in `Procfile` results in kill signals to properly propagate so
   `kill-ports` shouldn't be needed
3. I removed unnecessary scripts section from package.json file

Signed-off-by: Bart Smykla <[email protected]>

Makefile

@@ -28,9 +28,6 @@ test:
 build: ruby-version-check
 	bundle exec jekyll build --config jekyll.yml --profile
 
-serve:
-	yarn run dev
-
 # Cleans up all temp files in the build.
 # Run `make clean` locally whenever you're updating dependencies, or to help
 # troubleshoot build issues.
@@ -41,5 +38,11 @@ clean:
 	-rm -rf .jekyll-cache/vite
 
 kill-ports:
+	@echo '[DEPRECATED]: This target is deprecated because the "run" target now correctly handles kill signals, closing these ports automatically.'
+	@printf "  Existing Jekyll Processes on Port 4000 : %s\n" "$$(lsof -ti:4000 | tr '\n' ' ' || echo 'None')"
+	@printf "  Existing Vite Processes on Port 3036   : %s\n" "$$(lsof -ti:3036 | tr '\n' ' ' || echo 'None')"
+	@echo 'If you still want to terminate these processes, use the "kill-ports-force" target. [WARNING]: If you are using Firefox, this action may unexpectedly kill your browser processes.'
+
+kill-ports-force:
 	@JEKYLL_PROCESS=$$(lsof -ti:4000) && kill -9 $$JEKYLL_PROCESS || true
 	@VITE_PROCESS=$$(lsof -ti:3036) && kill -9 $$VITE_PROCESS || true

Procfile

@@ -1,2 +1,2 @@
-vite: bin/vite dev
-jekyll: bin/jekyll-vite wait && bundle exec jekyll serve --livereload --config jekyll-dev.yml
+netlify: npx netlify dev
+jekyll: bundle exec jekyll serve --livereload --config jekyll-dev.yml

app/_assets/javascripts/navbar.js

@@ -30,9 +30,7 @@ export default class NavBar {
       }
     });
 
-    this.sidebarButton.addEventListener('click', (event) => {
-      this.toggleSidebar();
-    });
+    this.sidebarButton?.addEventListener('click', () => this.toggleSidebar());
   }
 
   toggleSidebar(toggle) {

app/_assets/javascripts/prism.js

@@ -1,27 +1,33 @@
 import Prism from 'prismjs'
-import 'prismjs/plugins/line-numbers/prism-line-numbers.min.js'
-import 'prismjs/components/prism-bash.min.js'
-import 'prismjs/components/prism-systemd.min.js'
-import 'prismjs/components/prism-yaml.min.js'
-import 'prismjs/components/prism-json.min.js'
-
-import 'prismjs/plugins/show-language/prism-show-language.min.js'
-import 'prismjs/plugins/autoloader/prism-autoloader.min.js'
-import 'prismjs/plugins/toolbar/prism-toolbar.min.js'
-import 'prismjs/plugins/toolbar/prism-toolbar.min.css'
-import "prismjs/plugins/copy-to-clipboard/prism-copy-to-clipboard.min.js";
-
-import 'prismjs/themes/prism.min.css'
-import "prismjs/themes/prism-tomorrow.min.css";
-import 'prismjs/plugins/line-numbers/prism-line-numbers.min.css'
 
+import 'prismjs/components/prism-bash.js'
+import 'prismjs/components/prism-systemd.js'
+import 'prismjs/components/prism-yaml.js'
+import 'prismjs/components/prism-json.js'
+import 'prismjs/plugins/autoloader/prism-autoloader.js'
+import 'prismjs/plugins/line-numbers/prism-line-numbers.js'
+import 'prismjs/plugins/toolbar/prism-toolbar.js'
+import 'prismjs/plugins/copy-to-clipboard/prism-copy-to-clipboard.js'
+// styles
+import 'prismjs/themes/prism.css'
+import 'prismjs/plugins/line-numbers/prism-line-numbers.css'
+import 'prismjs/plugins/toolbar/prism-toolbar.css'
 import '@/styles/prismjs/prism-vs.scss'
 
 Prism.highlightAll();
 
-document.addEventListener('DOMContentLoaded', (event) => {
+const icon = `
+<span>
+  <svg data-v-49140617="" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" class="hover">
+    <path data-v-49140617="" fill="none" d="M0 0h24v24H0z"></path>
+    <path data-v-49140617="" fill="#4e1999" d="M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12V1zm-1 4l6 6v10c0 1.1-.9 2-2 2H7.99C6.89 23 6 22.1 6 21l.01-14c0-1.1.89-2 1.99-2h7zm-1 7h5.5L14 6.5V12z"></path>
+  </svg>
+</span>
+<span>Copied!</span>
+`;
+
+document.addEventListener('DOMContentLoaded', () => {
   document.querySelectorAll('.copy-to-clipboard-button').forEach((elem) => {
-    let icon = '<span><svg data-v-49140617="" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" class="hover"><path data-v-49140617="" fill="none" d="M0 0h24v24H0z"></path> <path data-v-49140617="" fill="#4e1999" d="M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12V1zm-1 4l6 6v10c0 1.1-.9 2-2 2H7.99C6.89 23 6 22.1 6 21l.01-14c0-1.1.89-2 1.99-2h7zm-1 7h5.5L14 6.5V12z"></path></svg></span>';
-    elem.innerHTML = icon + '<span>Copied!</span>';
+    elem.innerHTML = icon;
   });
 });

app/_assets/javascripts/sidebar.js

@@ -3,7 +3,6 @@ export default class Sidebar {
     this.elem = document.querySelector('.theme-container:not(.no-sidebar) #sidebar');
 
     if (this.elem !== null) {
-
       this.groups = Array.from(
         this.elem.querySelectorAll('.sidebar-links li .sidebar-group')
       );
@@ -56,35 +55,26 @@ export default class Sidebar {
   expandActiveGroup() {
     const currentPath = window.location.pathname;
     const activeLink = this.elem.querySelector(`a[href^='${currentPath}']`);
-    if (activeLink) {
-      const topLevelGroup = activeLink.closest(`.sidebar-group.depth-0`);
 
-      if (topLevelGroup !== null) {
-        this.toggleGroup(topLevelGroup);
+    if (activeLink) {
+      let currentGroup = activeLink.closest('.sidebar-group');
 
-        const nestedGroup = activeLink.closest(`.sidebar-group.depth-1`);
-        if (nestedGroup !== null) {
-          this.toggleGroup(nestedGroup);
-          nestedGroup.scrollIntoView({ behavior: "smooth", block: "center" });
-        } else {
-          topLevelGroup.scrollIntoView({ behavior: "smooth", block: "center" });
-        }
+      // Traverse up and expand each nested group until reaching the top level
+      while (currentGroup) {
+        this.toggleGroup(currentGroup, false);
+        currentGroup = currentGroup.parentNode.closest('.sidebar-group');
       }
+
+      this.elem.querySelector('.sidebar-links')?.scroll({ top: activeLink.offsetTop, behavior: 'smooth' });
     }
   }
 
   setActiveLink() {
-    let currentPath = window.location.pathname;
-    if (window.location.hash) {
-      currentPath += window.location.hash;
-    }
+    const currentPath = `${window.location.pathname}${window.location.hash || ''}`;
+    const activeLink = this.elem.querySelector(`a[href='${currentPath}']`);
 
-    let activeElement = this.elem
-      .querySelector(`a[href='${currentPath}']`);
-
-    if (activeElement !== null) {
-      activeElement.classList
-      .add('active');
+    if (activeLink) {
+      activeLink.classList.add('active');
     }
   }
 }

app/_assets/styles/custom/components/_sidebar.scss

@@ -44,6 +44,12 @@ $sidebar-button-left-spacing: 1.5rem;
   .nav-links {
     display: block;
   }
+
+  .sidebar-top-section {
+    padding-bottom: 1rem;
+    background: #fff;
+    mask-image: linear-gradient(to bottom, #fff 90%, transparent);
+  }
 }
 
 .sidebar-links {
@@ -91,9 +97,16 @@ a.sidebar-link {
   .sidebar {
     position: sticky;
     top: 0;
-    padding-top: $navbarHeight;
     bottom: 0;
-    height: calc(100vh - #{$navbarHeight});
+    height: 100vh;
+  }
+
+  .sidebar .sidebar-top-section {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    padding-top: $navbarHeight;
+    padding-bottom: 3rem;
   }
 
   .theme-container.no-sidebar .sidebar {

app/_assets/styles/custom/components/_version-alert.scss

@@ -4,16 +4,17 @@
 // This is the component that alerts the user if they are
 // viewing documentation for an older version, and provides
 // them with a link to the latest version.
-// 
+//
 
-$version-alert-max-width: 740px;
+$version-alert-max-width: $contentWidth;
 $version-alert-margin: $navbarHeight auto 0 auto;
 $version-alert-padding: 2rem 2.5rem 0 2rem;
 $version-alert-title-font-size: 1.5rem;
 $version-alert-title-margin: 0;
 $version-alert-text-margin: 0;
 $version-alert-inner-padding: 1.5rem;
 $version-alert-inner-margin: 0;
+$version-alert-inner-margin-large: 0 0 0 0.5rem;
 $version-alert-link-color: $color-5;
 
 .version-alert {
@@ -24,6 +25,9 @@ $version-alert-link-color: $color-5;
   .custom-block {
     padding: $version-alert-inner-padding;
     margin: $version-alert-inner-margin;
+    @media (min-width: $MQMobile) {
+      margin: $version-alert-inner-margin-large;
+    }
 
     a {
       text-decoration: underline;

app/_assets/styles/prismjs/prism-vs.scss

@@ -128,12 +128,12 @@
  .token.property,
  .token.regex,
  .token.entity {
-     color: #ff0000;
+   color: #ff0000;
  }
 
  .token.directive.tag  .tag {
-     background: #ffff00;
-     color: #393A34;
+   background: #ffff00;
+   color: #393A34;
  }
 
  /* overrides color-values for the Line Numbers plugin
@@ -154,28 +154,41 @@
  */
  .line-highlight {
    background: rgba(193, 222, 241, 0.2);
-   background: -webkit-linear-gradient(left, rgba(193, 222, 241, 0.2) 70%, rgba(221, 222, 241, 0));
+   background: -webkit-linear-gradient(to left, rgba(193, 222, 241, 0.2) 70%, rgba(221, 222, 241, 0));
    background: linear-gradient(to right, rgba(193, 222, 241, 0.2) 70%, rgba(221, 222, 241, 0));
  }
 
  .copy-to-clipboard-button {
    background: none !important;
    box-shadow: none !important;
 
-   svg {
-     bottom: 7.5px;
-     margin-right: 15px;
-   }
-
    &[data-copy-state='copy'] span:nth-child(2) {
      display: none;
    }
+
    &[data-copy-state='copy-success'] span:nth-child(2) {
      color: #393a34;
      position: absolute;
+     top: 15px;
+     right: 40px;
      font-size: 13.6px;
      line-height: 6.8px;
-     right: 50px;
      transition: opacity .5s;
    }
+
+   &:hover span:first-child {
+     opacity: 0.7;
+   }
  }
+
+div[class*="language-"] {
+  &::before {
+    opacity: 1;
+    transition: opacity .25s ease-in-out;
+  }
+
+  &:hover::before, &:focus-within::before {
+    opacity: 0;
+    transition: opacity .25s ease-in-out;
+  }
+}