Merge remote-tracking branch 'origin/master' into separate-install

# Conflicts:
#	.github/styles/config/vocabularies/Base/reject.txt

.github/styles/config/vocabularies/Base/accept.txt

@@ -155,6 +155,7 @@ Syslog
 target[Rr]ef
 tbl
 tcpdump
+TCP
 TLS
 transcoder
 ttl

.github/styles/config/vocabularies/Base/reject.txt

@@ -2,6 +2,7 @@ control-plane
 controlplane
 data-plane
 dataplane
+tcp
 multizone
 multi\s+zone
 singlezone

Gemfile.lock

@@ -86,7 +86,7 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.3.8)
+    rexml (3.3.9)
     rouge (3.30.0)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)

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

WRITING-DOCUMENTATION.md

@@ -1,3 +1,4 @@
+<!-- vale off -->
 # Writing documentation
 
 After starting the site locally, navigate to `http://localhost:8080/docs/`. This is where you can view your work 
@@ -57,6 +58,44 @@ You can use [https://mermaid.live/edit](https://mermaid.live/edit) to generate d
 
 **Note:** Currently, Mermaid isn't supported in navtabs.
 
+## Jekyll plugins
+
+You can use some custom plugins to make writing documentation easier, especially for things Jekyll doesn’t support by default:
+
+### `inc` tag
+
+The `inc` plugin increments a variable (like `step_number`) each time it's called, letting you keep step numbers or counts consistent across your documentation. You can also set conditions to control when it increments based on the Kuma version or set an initial value.
+
+The first parameter, such as `step_number`, is the variable name used to differentiate between counters. This parameter is required for each `inc` tag.
+
+Parameter order doesn’t matter, and values can be wrapped with either `''` or `""`. If you need to specify multiple version requirements for the `if_version` parameter, you must use quotes around the version string, for example: `{% inc step_number if_version="gte:2.4.x lte:2.8.x" %}`.
+
+#### How to use
+
+- **Basic increment**: `{% inc step_number %}` increments `step_number` by 1.
+- **Conditional increment**: `{% inc step_number if_version=lte:2.4.x %}` increments only if the Kuma version is `2.4.x` or lower.
+- **Set initial value**: `{% inc step_number init_value=5 %}` starts `step_number` at 5.
+- **Get current value**: `{% inc step_number get_current %}` returns the current value of `step_number` without incrementing.
+- **Get current value with initial value**: `{% inc step_number get_current init_value=7 %}` returns the current value of `step_number` without incrementing, starting at 7 if it hasn’t been set before.
+
+#### Available parameters
+
+- **if_version**: Only increments if the Kuma version matches (works like `{% if_version ... %}`).
+- **init_value**: Sets a starting value for the variable.
+- **get_current**: If `true`, returns the current value without incrementing.
+
+#### Real-life examples
+
+```liquid
+{% if_version lte:2.4.x %}
+## Step {% inc step_number if_version=lte:2.4.x %}: Ensure the correct version of iptables.
+{% endif_version %}
+```
+
+```liquid
+To prepare your service environment and start the data plane proxy, follow the [Integrating Transparent Proxy into Your Service Environment](...) guide up to [Step {% inc install_tproxy if_version="lte:2.4.x" init_value=5 %}: Install the Transparent Proxy](...).
+```
+
 ## Cutting a new release
 
 To cut the dev release, create a duplicate of the [docs_nav_kuma_dev.yml](app/_data/docs_nav_kuma_dev.yml) file and then rename one of the files to "docs_nav_kuma_[version].yml". Update the `release: dev` metadata in the new release file with the release version.

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;