feat(mermaid): Add Mermaid.js diagrams plugin (#1547)

Add Mermaid diagrams

Signed-off-by: Diana <[email protected]>

.vale.ini

@@ -7,10 +7,3 @@ Packages = Google
 
 [*.md]
 BasedOnStyles = Vale, Google
-BlockIgnores = (\((http.*://|\.\/|\/).*?\)), \
-{\:.*?}
-TokenIgnores = {%.*?%}, \
-{{.*?}}, \
-(?:)(/[(A-Za-z0-9)(\055/)(_)]*/), \
-({\#.*})
-SkippedScopes = code

Gemfile.lock

@@ -103,7 +103,6 @@ GEM
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
-  arm64-darwin-23
   x86_64-darwin-21
   x86_64-darwin-22
   x86_64-linux

WRITING-DOCUMENTATION.md

@@ -29,6 +29,34 @@ The team is moving diagrams to [Google slides](https://docs.google.com/presentat
 Instructions are in the first slide.
 Ask a maintainer to get write access.
 
+### Mermaid.js diagrams
+
+You can use Mermaid.js diagrams in our documentation. It can be used with the following syntax: 
+```
+{% mermaid %}
+{% endmermaid %}
+```
+
+For example, if you wanted to make a flowchart, you can use the following syntax:
+```
+{% mermaid %}
+flowchart TD
+    A[Christmas] -->|Get money| B(Go shopping)
+    B --> C{Let me think}
+    C -->|One| D[Laptop]
+    C -->|Two| E[iPhone]
+    C -->|Three| F[fa:fa-car Car]
+{% endmermaid %}
+```
+
+This flowchart would render like the following in the docs:
+
+![Mermaid flowchart example](/assets/images/diagrams/mermaid-example.png)
+
+You can use [https://mermaid.live/edit](https://mermaid.live/edit) to generate diagrams and see the rendered output before adding it to docs.
+
+**Note:** Currently, Mermaid isn't supported in navtabs.
+
 ## 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/styles/custom/base/_type-and-content.scss

@@ -90,7 +90,11 @@ div[class*='language-'] {
   pre[class*='language-'],
   div[class*='language-'] {
     background-color: $codeBgColor;
-
+
+    &.mermaid {
+      background-color: unset;
+    }
+
     code {
       font-size: 0.9rem;
       line-height: 1.5;

app/_data/docs_nav_kuma_dev.yml

@@ -254,10 +254,28 @@ items:
     items:
       - text: Introduction
         url: /policies/introduction/
+      - text: General notes about Kuma policies
+        url: /policies/general-notes-about-kuma-policies/
       - text: Applying Policies
         url: /policies/applying-policies/
+      - text: How Kuma chooses the right policy to apply
+        url: /policies/how-kuma-chooses-the-right-policy-to-apply/
+        items:
+          - text: General rules
+            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#general-rules"
+          - text: Combine Policies to Avoid Overriding
+            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#combine-policies-to-avoid-overriding"
+          - text: Dataplane Policy
+            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#dataplane-policy"
+          - text: Connection policies
+            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#connection-policies"
+          - text: Outbound Connection Policy
+            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#outbound-connection-policy"
+          - text: Inbound Connection Policy
+            url: "/policies/how-kuma-chooses-the-right-policy-to-apply/#inbound-connection-policy"
       - text: Understanding TargetRef policies
         url: "/policies/targetref"
+
       - text: Protocol support in Kuma
         url: /policies/protocol-support-in-kuma/
         items:
@@ -278,20 +296,128 @@ items:
             url: "/policies/mutual-tls/#permissive-mtls"
           - text: Certificate Rotation
             url: "/policies/mutual-tls/#certificate-rotation"
+      - text: Traffic Permissions
+        url: /policies/traffic-permissions/
+        items:
+          - text: Usage
+            url: "/policies/traffic-permissions/#usage"
+          - text: Access to External Services
+            url: "/policies/traffic-permissions/#access-to-external-services"
+      - text: Traffic Route
+        url: /policies/traffic-route/
+        items:
+          - text: Usage
+            url: "/policies/traffic-route/#usage"
+      - text: Traffic Metrics
+        url: /policies/traffic-metrics/
+        items:
+          - text: Expose metrics from data plane proxies
+            url: "/policies/traffic-metrics/#expose-metrics-from-data-plane-proxies"
+          - text: Expose metrics from applications
+            url: "/policies/traffic-metrics/#expose-metrics-from-applications"
+          - text: Override Prometheus settings per data plane proxy
+            url: "/policies/traffic-metrics/#override-prometheus-settings-per-data-plane-proxy"
+          - text: Filter Envoy metrics
+            url: "/policies/traffic-metrics/#filter-envoy-metrics"
+          - text: Secure data plane proxy metrics
+            url: "/policies/traffic-metrics/#secure-data-plane-proxy-metrics"
+      - text: Traffic Trace
+        url: /policies/traffic-trace/
+        items:
+          - text: Add a tracing backend to the mesh
+            url: "/policies/traffic-trace/#add-a-tracing-backend-to-the-mesh"
+          - text: Add TrafficTrace resource
+            url: "/policies/traffic-trace/#add-traffictrace-resource"
+      - text: Traffic Log
+        url: /policies/traffic-log/
+        items:
+          - text: Add a logging backend
+            url: "/policies/traffic-log/#add-a-logging-backend"
+          - text: Add a TrafficLog resource
+            url: "/policies/traffic-log/#add-a-trafficlog-resource"
+          - text: Logging external services
+            url: "/policies/traffic-log/#logging-external-services"
+          - text: Builtin Gateway support
+            url: "/policies/traffic-log/#builtin-gateway-support"
+          - text: Access Log Format
+            url: "/policies/traffic-log/#access-log-format"
+      - text: Locality-aware Load Balancing
+        url: /policies/locality-aware/
+        items:
+          - text: Enabling locality-aware load balancing
+            url: "/policies/locality-aware/#enabling-locality-aware-load-balancing"
+      - text: Fault Injection
+        url: /policies/fault-injection/
+        items:
+          - text: Usage
+            url: "/policies/fault-injection/#usage"
+          - text: Matching
+            url: "/policies/fault-injection/#matching"
+      - text: Health Check
+        url: /policies/health-check/
+        items:
+          - text: Usage
+            url: "/policies/health-check/#usage"
+          - text: Matching
+            url: "/policies/health-check/#matching"
+      - text: Circuit Breaker
+        url: /policies/circuit-breaker/
+        items:
+          - text: Usage
+            url: "/policies/circuit-breaker/#usage"
+          - text: Matching
+            url: "/policies/circuit-breaker/#matching"
+          - text: Builtin Gateway support
+            url: "/policies/circuit-breaker/#builtin-gateway-support"
+          - text: Non-mesh traffic
+            url: "/policies/circuit-breaker/#non-mesh-traffic"
       - text: External Service
         url: /policies/external-services/
         items:
           - text: Usage
             url: "/policies/external-services/#usage"
           - text: Builtin Gateway support
             url: "/policies/external-services/#builtin-gateway-support"
-      - text: Service Health Probes
-        url: /policies/service-health-probes/
+      - text: Retry
+        url: /policies/retry/
         items:
-          - text: Kubernetes
-            url: "/policies/service-health-probes/#kubernetes"
-          - text: Universal probes
-            url: "/policies/service-health-probes/#universal-probes"
+          - text: Usage
+            url: "/policies/retry/#usage"
+          - text: Matching
+            url: "/policies/retry/#matching"
+          - text: Builtin Gateway support
+            url: "/policies/retry/#builtin-gateway-support"
+      - text: Timeout
+        url: /policies/timeout/
+        items:
+          - text: Usage
+            url: "/policies/timeout/#usage"
+          - text: Configuration
+            url: "/policies/timeout/#configuration"
+          - text: Default general-purpose Timeout policy
+            url: "/policies/timeout/#default-general-purpose-timeout-policy"
+          - text: Matching
+            url: "/policies/timeout/#matching"
+          - text: Builtin Gateway support
+            url: "/policies/timeout/#builtin-gateway-support"
+          - text: Inbound timeouts
+            url: "/policies/timeout/#inbound-timeouts"
+          - text: Non-mesh traffic
+            url: "/policies/timeout/#non-mesh-traffic"
+      - text: Rate Limit
+        url: /policies/rate-limit/
+        items:
+          - text: Usage
+            url: "/policies/rate-limit/#usage"
+          - text: Matching destinations
+            url: "/policies/rate-limit/#matching-destinations"
+          - text: Builtin Gateway support
+            url: "/policies/rate-limit/#builtin-gateway-support"
+      - text: Virtual Outbound
+        url: /policies/virtual-outbound/
+        items:
+          - text: Examples
+            url: "/policies/virtual-outbound/#examples"
       - text: MeshGateway
         url: /policies/meshgateway/
         items:
@@ -310,6 +436,13 @@ items:
             url: "/policies/meshgatewayroute/#reference"
       - text: MeshGatewayInstance
         url: /policies/meshgatewayinstance/
+      - text: Service Health Probes
+        url: /policies/service-health-probes/
+        items:
+          - text: Kubernetes
+            url: "/policies/service-health-probes/#kubernetes"
+          - text: Universal probes
+            url: "/policies/service-health-probes/#universal-probes"
       - text: MeshAccessLog
         url: /policies/meshaccesslog/
         items:
@@ -357,15 +490,6 @@ items:
             url: "/policies/meshhttproute/#examples"
           - text: Merging
             url: "/policies/meshhttproute/#merging"
-      - text: MeshMetric
-        url: /policies/meshmetric/
-        items:
-          - text: TargetRef support matrix
-            url: "/policies/meshmetric/#targetref-support-matrix"
-          - text: Configuration
-            url: "/policies/meshmetric/#configuration"
-          - text: Examples
-            url: "/policies/meshmetric/#examples"
       - text: MeshProxyPatch
         url: /policies/meshproxypatch/
         items:
@@ -442,39 +566,6 @@ items:
             url: "/policies/meshloadbalancingstrategy/#configuration"
           - text: Examples
             url: "/policies/meshloadbalancingstrategy/#examples"
-      - title: Previous Policies
-        group: true
-        items:
-          - text: General notes about Kuma policies
-            url: /policies/general-notes-about-kuma-policies/
-          - text: How Kuma chooses the right policy to apply
-            url: /policies/how-kuma-chooses-the-right-policy-to-apply/
-          - text: Traffic Permissions
-            url: /policies/traffic-permissions/
-          - text: Traffic Route
-            url: /policies/traffic-route/
-          - text: Traffic Metrics
-            url: /policies/traffic-metrics/
-          - text: Traffic Trace
-            url: /policies/traffic-trace/
-          - text: Traffic Log
-            url: /policies/traffic-log/
-          - text: Locality-aware Load Balancing
-            url: /policies/locality-aware/
-          - text: Fault Injection
-            url: /policies/fault-injection/
-          - text: Health Check
-            url: /policies/health-check/
-          - text: Circuit Breaker
-            url: /policies/circuit-breaker/
-          - text: Retry
-            url: /policies/retry/
-          - text: Timeout
-            url: /policies/timeout/
-          - text: Rate Limit
-            url: /policies/rate-limit/
-          - text: Virtual Outbound
-            url: /policies/virtual-outbound/
   - title: Reference
     group: true
     items:

app/_data/navigation.yml

@@ -1,6 +1,6 @@
-- text: "Explore Features"
-  url: "/features/"
-  key: "features"
+- text: "Explore Policies"
+  url: "/policies/"
+  key: "policies"
 - text: "Docs"
   url: "/docs/"
   key: "docs"

app/_data/versions.yml

@@ -71,7 +71,7 @@
   endOfLifeDate: "2024-08-29"
   branch: release-2.4
 - edition: kuma
-  version: 2.5.1
+  version: 2.5.0
   release: 2.5.x
   latest: true
   releaseDate: "2023-11-15"

app/_includes/distribution_dropdown.html

@@ -22,8 +22,8 @@
 
     <ul class="hidden options-list">
       <li>
-        <a href="/install">
-          OSS
+        <a href="/enterprise">
+          Schedule a demo
           <span class="ml-2">
             <svg
               width="18"
@@ -40,13 +40,12 @@
                 stroke-linejoin="miter"
               />
             </svg>
-
           </span>
         </a>
       </li>
       <li>
-        <a href="/enterprise">
-          Schedule a demo
+        <a href="/install">
+          OSS
           <span class="ml-2">
             <svg
               width="18"
@@ -63,6 +62,7 @@
                 stroke-linejoin="miter"
               />
             </svg>
+
           </span>
         </a>
       </li>

app/_includes/snippets/install_kumactl.md

@@ -33,7 +33,7 @@ Once downloaded, you will find the contents of Kuma in the `kuma-{{ page.latest_
 
 So we enter the `bin` folder by executing: `cd kuma-{{ page.latest_version }}/bin`
 
-We suggest adding the `kumactl` executable to your `PATH` (by executing: `export PATH=$(pwd):$PATH`) so that it's always available in every working directory. Or - alternatively - you can also create link in `/usr/local/bin/` by executing:
+We suggest adding the `kumactl` executable to your `PATH` (by executing: `PATH=$(pwd):$PATH`) so that it's always available in every working directory. Or - alternatively - you can also create link in `/usr/local/bin/` by executing:
 
 ```sh
 ln -s $PWD/kuma-{{ page.latest_version }}/bin/kumactl /usr/local/bin/kumactl