From 337a2f3f84ec0af495a0fab895cda4ec9686f834 Mon Sep 17 00:00:00 2001 From: Ranbel Sun Date: Thu, 3 Apr 2025 13:42:52 -0400 Subject: [PATCH] placeholder variables --- .../guidelines-for-curl-commands.mdx | 4 ++-- .../formatting/code-conventions-and-format.mdx | 18 +++++++----------- 2 files changed, 9 insertions(+), 13 deletions(-) diff --git a/src/content/docs/style-guide/api-content-strategy/guidelines-for-curl-commands.mdx b/src/content/docs/style-guide/api-content-strategy/guidelines-for-curl-commands.mdx index 130ff9d756526aa..0a568f2bfae3037 100644 --- a/src/content/docs/style-guide/api-content-strategy/guidelines-for-curl-commands.mdx +++ b/src/content/docs/style-guide/api-content-strategy/guidelines-for-curl-commands.mdx @@ -15,7 +15,7 @@ To automatically incorporate our conventions into your examples, use: - [`APIRequest`](/style-guide/components/api-request/): For examples hitting endpoints in the Cloudflare API schema. - [`CURL`](/style-guide/components/curl/): For other cURL commands. -## Paramter names +## Parameter names Use long parameter names for clarity: @@ -45,7 +45,7 @@ If you must suggest the use of this tool, you can add a link to the [Make API ca * Make sure not to use typographical or smart quotes in a cURL command, or the command will fail. * Placeholders in the URL should follow the same format as in the API documentation: `$ZONE_ID` -* Placeholders in the request body (that is, the data included in a `POST`/`PUT`/`PATCH` request) should use this format: `` +* Placeholders in the request body (that is, the data included in a `POST`/`PUT`/`PATCH` request) should use [angle brackets](/style-guide/formatting/code-conventions-and-format/#angle-brackets---and--): `` The same placeholder name should correspond to the same value – use different placeholder names for different ID values. You can use the same request placeholders in the response, if they should match the values in the request. diff --git a/src/content/docs/style-guide/formatting/code-conventions-and-format.mdx b/src/content/docs/style-guide/formatting/code-conventions-and-format.mdx index 2d7939559786410..ade2659ac2b5ff4 100644 --- a/src/content/docs/style-guide/formatting/code-conventions-and-format.mdx +++ b/src/content/docs/style-guide/formatting/code-conventions-and-format.mdx @@ -8,11 +8,9 @@ Use the conventions described below throughout Cloudflare product content. ## Angle brackets ( `<` and `>` ) -Use angle brackets as a placeholder for variables you want the user to enter (except in URLs, where you should use curly braces for placeholders). +Use angle brackets to denote placeholders for variables you want the user to enter (except in [API URLs and API authentication headers](/style-guide/api-content-strategy/guidelines-for-curl-commands/#request-guidelines), where you should use the `$ZONE_ID` / `$CLOUDFLARE_API_TOKEN` format). Placeholder text should have all capital letters and use underscores (`_`) to separate words. -Example: - -Type your user-specified domain in this format: `https://.cloudflare.com` +Examples: ``` { @@ -20,6 +18,10 @@ Type your user-specified domain in this format: `https:// } ``` +``` +https://.cloudflare.com +``` + Angle brackets that contain numbers separated by an ellipsis represent a range of values associated with a bit or single name - for example, AO `<0...3>`. ## Square brackets ( `[` and `]` ) @@ -32,13 +34,7 @@ Specify a subsearch that starts with this search command: `tag=dns query [search ## Curly braces ( `{` and `}` ) -Use curly braces in the following situations, such as: - -When they are part of a code sample or other string literal, such as in placeholders inside a URL. - -Example: - -`https://api.cloudflare.com/client/v4/organizations/{organization_identifier}/invites` +Do not use curly braces for URL or variable placeholders. Instead, refer to [angle brackets](#angle-brackets---and--). ## >