From ee1f8bae2e0b9286a3e95a9c6e1f3ad0370b5386 Mon Sep 17 00:00:00 2001
From: Roman Khavronenko <roman@victoriametrics.com>
Date: Mon, 16 May 2022 09:27:19 +0200
Subject: [PATCH] docs: fix liquid syntax errors (#2592)

For liquid text processor double braces `{{` `}}`
are special chars for templating.
Since we use them in some of our docs with different purpose,
we must escape them to avoid syntax errors from liquid.

For escaping curly braces we use bult-in plugin which helps
to enclose sections of text via `{% raw %}` and `{% endraw %}`.
This approach prevents liquid syntax errors and makes render correct.

Signed-off-by: hagen1778 <roman@victoriametrics.com>
---
 app/vmalert/README.md        | 4 ++++
 docs/PerTenantStatistic.md   | 2 ++
 docs/operator/quick-start.MD | 6 ++++++
 docs/vmalert.md              | 4 ++++
 4 files changed, 16 insertions(+)

diff --git a/app/vmalert/README.md b/app/vmalert/README.md
index e89fb259c..18fa20ae4 100644
--- a/app/vmalert/README.md
+++ b/app/vmalert/README.md
@@ -197,6 +197,7 @@ set the path via `-rule.templates` flag.
 
 For example, template `grafana.filter` can be defined as following:
 
+{% raw  %}
 ```
 {{ define "grafana.filter" -}}
   {{- $labels := .arg0 -}}
@@ -207,9 +208,11 @@ For example, template `grafana.filter` can be defined as following:
   {{- end -}}
 {{- end -}}
 ```
+{% endraw %}
 
 And then used in annotations:
 
+{% raw  %}
 ```yaml
 groups:
   - name: AlertGroupName
@@ -223,6 +226,7 @@ groups:
         annotations:
           dashboard: '{{ $externalURL }}/d/dashboard?orgId=1{{ template "grafana.filter" (args .CommonLabels "account_id" "any_label") }}'
 ```
+{% endraw %}
 
 The `-rule.templates` flag supports wildcards so multiple files with templates can be loaded.
 The content of `-rule.templates` can be also [hot reloaded](#hot-config-reload).
diff --git a/docs/PerTenantStatistic.md b/docs/PerTenantStatistic.md
index 7768895bf..e798a7e11 100644
--- a/docs/PerTenantStatistic.md
+++ b/docs/PerTenantStatistic.md
@@ -60,6 +60,7 @@ to prevent limits exhaustion.
 
 Here is an alert example for high churn rate by the tenant:
 
+{% raw  %}
 ```yaml
 
 - alert: TooHighChurnRate
@@ -79,3 +80,4 @@ Here is an alert example for high churn rate by the tenant:
             High Churn Rate is tightly connected with database performance and may
             result in unexpected OOM's or slow queries."
 ```
+{% endraw %}
diff --git a/docs/operator/quick-start.MD b/docs/operator/quick-start.MD
index c05e5a73e..ede19fdd0 100644
--- a/docs/operator/quick-start.MD
+++ b/docs/operator/quick-start.MD
@@ -752,6 +752,7 @@ kubectl logs vmalert-example-vmalert-6f8748c6f9-hcfrr vmalert
 
 Let's add simple rule for `VMAlert` itself, `delta(vmalert_config_last_reload_errors_total[5m]) > 1`
 
+{% raw %}
 ```yaml
 cat << 'EOF' | kubectl apply -f -
 apiVersion: operator.victoriametrics.com/v1beta1
@@ -775,6 +776,7 @@ spec:
             description: 'error reloading vmalert config, reload count for 5 min {{ $value }}'
 EOF
 ```
+{% endraw %}
 
  Ensure, that new alert was started:
  ```bash
@@ -790,6 +792,7 @@ kubectl logs vmalert-example-vmalert-6f8748c6f9-hcfrr vmalert
 
  Let's trigger it by adding some incorrect rule
  
+{% raw %}
 ```yaml
 cat << 'EOF' | kubectl apply -f -
 apiVersion: operator.victoriametrics.com/v1beta1
@@ -811,6 +814,7 @@ spec:
             value: "{{ $badValue | bad function }}"
 EOF
 ```
+{% endraw %}
 
 `VMAlert` will report incorrect rule config and fire alert:
 ```bash
@@ -1129,6 +1133,7 @@ vmauth-config-example   Opaque   1      2m32s
 ```
 
  Generated configuration can be retrieved with command:
+{% raw %}
 ```text
 kubectl get secrets/vmauth-config-example -o=go-template='{{index .data "config.yaml.gz"}}' | base64 -d | gunzip
 
@@ -1136,6 +1141,7 @@ users:
 - url_prefix: http://localhost:8428
   bearer_token: some-default-token
 ```
+{% endraw %}
 
   Operator generates default config, if `VMUser`s for given `VMAuth` wasn't found.
 
diff --git a/docs/vmalert.md b/docs/vmalert.md
index d7e4d53b0..d398ef830 100644
--- a/docs/vmalert.md
+++ b/docs/vmalert.md
@@ -201,6 +201,7 @@ set the path via `-rule.templates` flag.
 
 For example, template `grafana.filter` can be defined as following:
 
+{% raw  %}
 ```
 {{ define "grafana.filter" -}}
   {{- $labels := .arg0 -}}
@@ -211,9 +212,11 @@ For example, template `grafana.filter` can be defined as following:
   {{- end -}}
 {{- end -}}
 ```
+{% endraw %}
 
 And then used in annotations:
 
+{% raw  %}
 ```yaml
 groups:
   - name: AlertGroupName
@@ -227,6 +230,7 @@ groups:
         annotations:
           dashboard: '{{ $externalURL }}/d/dashboard?orgId=1{{ template "grafana.filter" (args .CommonLabels "account_id" "any_label") }}'
 ```
+{% endraw %}
 
 The `-rule.templates` flag supports wildcards so multiple files with templates can be loaded.
 The content of `-rule.templates` can be also [hot reloaded](#hot-config-reload).