[Rules] Add ref field to Terraform and API examples (cloudflare#22963)

Author: pedrosousa

src/content/docs/cache/how-to/cache-rules/terraform-example.mdx

@@ -8,7 +8,7 @@ head:
     content: Cache Rules — Terraform example
 ---
 
-import { Details } from "~/components";
+import { Details, Render } from "~/components";
 
 The following example defines a single cache rule for a zone using Terraform. The rule configures several cache settings and sets a custom cache key for incoming requests addressed at `example.net`.
 
@@ -82,6 +82,12 @@ resource "cloudflare_ruleset" "cache_rules_example" {
 }
 ```
 
+<Render
+	file="terraform-use-ref-field"
+	product="rules"
+	params={{ addDocsLocation: true }}
+/>
+
 </Details>
 
 For additional guidance on using Terraform with Cloudflare, refer to [Terraform](/terraform/).

src/content/docs/rules/compression-rules/examples/disable-all-brotli.mdx

@@ -9,7 +9,7 @@ description: Create a compression rule to turn off Brotli compression for all
   incoming requests of a given zone.
 ---
 
-import { Example, TabItem, Tabs, APIRequest } from "~/components";
+import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";
 
 <Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
 
@@ -40,6 +40,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	json={{
 		rules: [
 			{
+				ref: "always_use_gzip",
 				expression: "true",
 				action: "compress_response",
 				action_parameters: {
@@ -50,4 +51,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 </TabItem> </Tabs>

src/content/docs/rules/compression-rules/examples/disable-compression-avif.mdx

@@ -11,7 +11,7 @@ description: Create a compression rule to turn off compression for AVIF images,
   request.
 ---
 
-import { Example, TabItem, Tabs, APIRequest } from "~/components";
+import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";
 
 <Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
 
@@ -42,6 +42,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	json={{
 		rules: [
 			{
+				ref: "disable_compression_for_avif",
 				expression:
 					'http.response.content_type.media_type eq "image/avif" or http.request.uri.path.extension eq "avif"',
 				action: "compress_response",
@@ -53,4 +54,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 </TabItem> </Tabs>

src/content/docs/rules/compression-rules/examples/enable-zstandard.mdx

@@ -7,7 +7,7 @@ title: Enable Zstandard compression for default content types
 description: Create a compression rule to turn on Zstandard compression for response content types where Cloudflare applies compression by default.
 ---
 
-import { Example, TabItem, Tabs, APIRequest } from "~/components";
+import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";
 
 <Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
 
@@ -38,6 +38,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	json={{
 		rules: [
 			{
+				ref: "use_zstd_compression",
 				expression:
 					'(http.response.content_type.media_type in {"text/html" "text/richtext" "text/plain" "text/css" "text/x-script" "text/x-component" "text/x-java-source" "text/x-markdown" "application/javascript" "application/x-javascript" "text/javascript" "text/js" "image/x-icon" "image/vnd.microsoft.icon" "application/x-perl" "application/x-httpd-cgi" "text/xml" "application/xml" "application/rss+xml" "application/vnd.api+json" "application/x-protobuf" "application/json" "multipart/bag" "multipart/mixed" "application/xhtml+xml" "font/ttf" "font/otf" "font/x-woff" "image/svg+xml" "application/vnd.ms-fontobject" "application/ttf" "application/x-ttf" "application/otf" "application/x-otf" "application/truetype" "application/opentype" "application/x-opentype" "application/font-woff" "application/eot" "application/font" "application/font-sfnt" "application/wasm" "application/javascript-binast" "application/manifest+json" "application/ld+json" "application/graphql+json" "application/geo+json"})',
 				action: "compress_response",
@@ -49,4 +50,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 </TabItem> </Tabs>

src/content/docs/rules/compression-rules/examples/gzip-for-csv.mdx

@@ -9,7 +9,7 @@ description: Create a compression rule to set Gzip compression as the preferred
   compression method for CSV files.
 ---
 
-import { Example, TabItem, Tabs, APIRequest } from "~/components";
+import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";
 
 <Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
 
@@ -40,6 +40,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	json={{
 		rules: [
 			{
+				ref: "use_gzip_for_csv",
 				expression: 'http.request.uri.path.extension eq "csv"',
 				action: "compress_response",
 				action_parameters: {
@@ -50,4 +51,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 </TabItem> </Tabs>

src/content/docs/rules/compression-rules/examples/only-brotli-url-path.mdx

@@ -9,7 +9,7 @@ description: Create a compression rule to set Brotli as the only supported
   compression algorithm for a specific URI path.
 ---
 
-import { Example, TabItem, Tabs, APIRequest } from "~/components";
+import { Example, TabItem, Tabs, APIRequest, Render } from "~/components";
 
 <Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">
 
@@ -42,6 +42,7 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	json={{
 		rules: [
 			{
+				ref: "use_only_brotli_for_assets_tar",
 				expression: 'http.request.uri.path eq "/download/assets.tar"',
 				action: "compress_response",
 				action_parameters: {
@@ -52,4 +53,6 @@ The following example sets the rules of an existing [entry point ruleset](/rules
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 </TabItem> </Tabs>

src/content/docs/rules/configuration-rules/create-api.mdx

@@ -43,6 +43,7 @@ The following example sets the rules of an existing phase ruleset (`{ruleset_id}
 	json={{
 		rules: [
 			{
+				ref: "enable_email_obfuscation_bic",
 				expression: 'starts_with(http.request.uri.path, "/contact-us/")',
 				description:
 					"Obfuscates email addresses and enables BIC in contacts page",
@@ -56,6 +57,8 @@ The following example sets the rules of an existing phase ruleset (`{ruleset_id}
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 </Details>
 
 <Details header="Example: Add a rule that turns on Under Attack mode for the admin area">
@@ -68,6 +71,7 @@ The following example sets the rules of an existing phase ruleset (`{ruleset_id}
 	json={{
 		rules: [
 			{
+				ref: "enable_under_attack_in_admin",
 				expression: 'http.host eq "admin.example.com"',
 				description: "Turn on Under Attack mode for admin area",
 				action: "set_config",
@@ -79,6 +83,8 @@ The following example sets the rules of an existing phase ruleset (`{ruleset_id}
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 </Details>
 
 ---

src/content/docs/rules/configuration-rules/examples/define-single-configuration-terraform.mdx

@@ -37,4 +37,6 @@ resource "cloudflare_ruleset" "http_config_rules_example" {
 }
 ```
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 <Render file="terraform-additional-resources" />

src/content/docs/rules/custom-errors/create-rules.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 3
 ---
 
-import { APIRequest } from "~/components";
+import { APIRequest, Render } from "~/components";
 
 ## In the dashboard
 
@@ -111,6 +111,7 @@ This example configures a custom error rule returning a [previously created cust
 	json={{
 		rules: [
 			{
+				ref: "serve_500_template",
 				action: "serve_error",
 				action_parameters: {
 					asset_name: "500_error_template",
@@ -123,6 +124,8 @@ This example configures a custom error rule returning a [previously created cust
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.
 
 ## Required API token permissions

src/content/docs/rules/custom-errors/example-rules.mdx

@@ -5,7 +5,7 @@ sidebar:
   order: 4
 ---
 
-import { Tabs, TabItem, APIRequest } from "~/components";
+import { Tabs, TabItem, APIRequest, Render } from "~/components";
 
 The provided examples use the following fields in their rule expressions:
 
@@ -48,6 +48,7 @@ This example configures a custom JSON error response for all 5XX errors (`500`-`
 	json={{
 		rules: [
 			{
+				ref: "json_response_for_5xx_errors",
 				action: "serve_error",
 				action_parameters: {
 					content: '{"message": "A server error occurred."}',
@@ -61,6 +62,8 @@ This example configures a custom JSON error response for all 5XX errors (`500`-`
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.
 
 </TabItem> </Tabs>
@@ -103,6 +106,7 @@ This example configures a custom HTML error response for responses with a `500`
 	json={{
 		rules: [
 			{
+				ref: "html_response_500_to_503",
 				action: "serve_error",
 				action_parameters: {
 					content:
@@ -117,6 +121,8 @@ This example configures a custom HTML error response for responses with a `500`
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.
 
 </TabItem> </Tabs>
@@ -154,6 +160,7 @@ This example configures a custom HTML error response for [Cloudflare error 1020]
 	json={{
 		rules: [
 			{
+				ref: "html_response_cf_1020",
 				action: "serve_error",
 				action_parameters: {
 					content:
@@ -167,6 +174,8 @@ This example configures a custom HTML error response for [Cloudflare error 1020]
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.
 
 </TabItem> </Tabs>
@@ -204,6 +213,7 @@ This example configures a custom error rule returning a previously created custo
 	json={{
 		rules: [
 			{
+				ref: "serve_error_500_asset",
 				action: "serve_error",
 				action_parameters: {
 					asset_name: "500_error_template",
@@ -216,6 +226,8 @@ This example configures a custom error rule returning a previously created custo
 	}}
 />
 
+<Render file="terraform-use-ref-field" params={{ addDocsLocation: true }} />
+
 This `PUT` request, corresponding to the [Update a zone entry point ruleset](/api/resources/rulesets/subresources/phases/methods/update/) operation, replaces any existing rules in the `http_custom_errors` phase entry point ruleset.
 
 </TabItem> </Tabs>